MCP Gateway for Google Maps Scraper (MCP-GMS) es un servicio que proporciona una interfaz de pasarela para la funcionalidad de extracción de datos de Google Maps. Este servicio está construido utilizando FastAPI y está diseñado para ejecutarse en un entorno containerizado.
MCP-GMS/
├── api/
│ └── api_client.py # Implementación del cliente API
├── config/
│ └── config.py # Gestión de configuración
├── models/
│ └── models.py # Modelos de datos
├── resources/
│ └── resources.py # Gestión de recursos
├── tools/ # Herramientas MCP
│ ├── __init__.py # Registro y exportación de herramientas
│ ├── create_job.py # Herramienta para crear trabajos de scraping
│ ├── delete_job.py # Herramienta para eliminar trabajos
│ ├── download_results.py # Herramienta para descargar y procesar resultados
│ ├── get_job.py # Herramienta para obtener estado de trabajos
│ └── list_jobs.py # Herramienta para listar trabajos
├── tests/ # Pruebas unitarias
│ ├── test_api_client.py
│ └── test_tools.py
├── server.py # Servidor principal FastAPI
├── pyproject.toml # Dependencias y configuración del proyecto
└── uv.lock # Archivo de bloqueo de dependencias
- Python 3.10 o superior
- Docker (para despliegue containerizado)
El proyecto utiliza las siguientes dependencias principales:
- FastAPI (>=0.110) - Framework web para construcción de APIs
- HTTPX (>=0.27) - Cliente HTTP con soporte para HTTP/2
- Uvicorn (>=0.29) - Implementación de servidor ASGI
- Python-dotenv (>=1.0) - Gestión de variables de entorno
- Pydantic (>=2.7) - Validación de datos usando anotaciones de tipo Python
- MCP (>=0.1.0) - Funcionalidad central de MCP
Para desarrollo y pruebas, el proyecto requiere las siguientes dependencias adicionales:
- pytest (>=8.0.0) - Framework de pruebas
- pytest-asyncio (>=0.23.0) - Soporte para pruebas asíncronas
- pytest-mock (>=3.12.0) - Utilidades de mock para pruebas
- Asegúrate de tener Python 3.10+ instalado
- Instala el gestor de paquetes
uv - Clona el repositorio
- Navega al directorio del proyecto
- Crea un entorno virtual usando
uv:uv venv
- Activa el entorno virtual:
source .venv/bin/activate - Instala las dependencias incluyendo las de desarrollo:
uv pip install -e "src/[test]" - Ejecuta el servidor:
uv run python src/server.py
El proyecto incluye un Dockerfile para el despliegue containerizado. El Dockerfile utiliza un proceso de construcción multi-etapa para optimizar el tamaño de la imagen y la seguridad.
- Imagen Base: Utiliza
ghcr.io/astral-sh/uv:python3.11-bookworm-slimtanto para la etapa de construcción como para la de ejecución - Construcción Multi-etapa:
- Etapa de construcción:
- Instala las dependencias usando
uv - Copia y prepara el código de la aplicación
- Instala las dependencias usando
- Etapa de ejecución:
- Crea un usuario sin privilegios de root para seguridad
- Configura el entorno Python
- Expone el puerto 3000
- Etapa de construcción:
-
Construir la imagen:
docker build -t mcp-gms . -
Ejecutar el contenedor:
docker run -p 3000:3000 -e GMAPS_SCRAPER_USER=m***e -e GMAPS_SCRAPER_PASS=******
El proyecto incluye un conjunto de herramientas MCP para interactuar con la API de Google Maps Scraper:
- init.py: Registra y exporta todas las herramientas MCP disponibles
- create_job.py: Implementa la herramienta para crear nuevos trabajos de scraping con opciones configurables como:
- Nombre y palabras clave
- Configuración de idioma y zoom
- Coordenadas (latitud/longitud)
- Radio de búsqueda y profundidad
- Modo rápido y tiempo máximo
- Soporte para proxies
- delete_job.py: Permite eliminar trabajos de scraping existentes
- download_results.py: Gestiona la descarga y procesamiento de resultados con:
- Soporte para formatos CSV y JSON
- Estructuración automática de datos
- Paginación de resultados
- Manejo de metadatos
- get_job.py: Obtiene información detallada sobre el estado de un trabajo
- list_jobs.py: Lista todos los trabajos de scraping disponibles
El proyecto incluye un conjunto completo de pruebas unitarias para el cliente API y las herramientas MCP.
Para ejecutar todas las pruebas usando uv:
uv run --active pytest tests/ -vPara ejecutar un archivo de pruebas específico:
uv run --active pytest tests/test_api_client.py -vPara ejecutar una prueba específica:
uv run --active pytest tests/test_tools.py::test_create_scraping_job -vTambién puedes usar pytest directamente si estás en el entorno virtual:
pytest tests/ -vLas pruebas cubren:
- Cliente API (GMapsAPIClient)
- Creación, obtención, listado y eliminación de trabajos
- Descarga de resultados
- Validación de credenciales
- Herramientas MCP
- Validación de datos de entrada
- Manejo de errores
- Transformación de datos
- Funcionalidad de descarga en formatos CSV y JSON
- Procesamiento de resultados y estructuración de datos
- Gestión de trabajos y estados
La aplicación utiliza variables de entorno para su configuración. Crea un archivo .env en el directorio raíz con las variables necesarias.
- GMAPS_SCRAPER_URL=https://gmaps.foundation.vision
- GMAPS_SCRAPER_TIMEOUT=300
- MCP_SERVER_PORT=3000
- LOG_LEVEL=INFO
- GMAPS_SCRAPER_USER=m***e
- GMAPS_SCRAPER_PASS=******
La aplicación soporta dos modos de despliegue que se configuran mediante las siguientes variables:
- DEPLOYMENT_MODE=local
- MCP_SERVER_HOST=0.0.0.0
- MCP_SERVER_PORT=3000
- DEPLOYMENT_MODE=production
- MCP_PRODUCTION_URL=https://gms-mcp.foundation.vision
El modo local está diseñado para desarrollo y pruebas. En este modo:
- La aplicación se ejecuta en
0.0.0.0:3000 - Las URLs generadas usan el host y puerto local
- Ideal para desarrollo y pruebas locales
Para ejecutar en modo local:
DEPLOYMENT_MODE=local MCP_SERVER_HOST=0.0.0.0 MCP_SERVER_PORT=3000 uv run python server.pyEl modo producción está diseñado para despliegue en servidores. En este modo:
- Las URLs generadas usan la URL de producción configurada
- Soporta HTTPS y dominios personalizados
- Recomendado para ambientes de producción
Para ejecutar en modo producción:
DEPLOYMENT_MODE=production MCP_PRODUCTION_URL=https://gms-mcp.foundation.vision uv run python server.pyEl servicio proporciona endpoints para descargar resultados con soporte para paginación y múltiples formatos:
Descarga resultados paginados en formato JSON o CSV.
Parámetros:
format: Formato de descarga (jsonocsv)page: Número de página para resultados JSON (por defecto: 1)
Características de paginación JSON:
- 5 resultados por página
- Metadatos de paginación incluidos en la respuesta
- URLs para navegación entre páginas
- Información sobre resultados totales y restantes
Ejemplo de respuesta JSON:
{
"metadata": {
"job_id": "test123",
"total_places_found": 10,
"places_in_response": 5,
"remaining_places": 5,
"all_places_url": "https://gms-mcp.foundation.vision/api/v1/jobs/test123/download/all",
"pagination": {
"current_page": 1,
"total_pages": 2,
"previous_page_url": null,
"next_page_url": "https://gms-mcp.foundation.vision/api/v1/jobs/test123/download?page=2"
}
},
"places": [...]
}Descarga todos los resultados sin paginación.
Parámetros:
format: Formato de descarga (jsonocsv)
Este endpoint es útil cuando necesitas todos los resultados en una sola respuesta.
El proyecto utiliza Ruff para el formateo y linting del código con la siguiente configuración:
- Longitud de línea: 100 caracteres
- Reglas seleccionadas: E (pycodestyle), F (pyflakes), I (isort)
- Organización personalizada de importaciones para módulos del proyecto
- El contenedor Docker se ejecuta bajo un usuario sin privilegios de root para mayor seguridad
- Las dependencias están bloqueadas usando
uv.lockpara garantizar builds reproducibles - Soporte para HTTP/2 habilitado para mejor rendimiento y seguridad