MapmyIndia (Mappls) MCP Server (FastMCP)

Un servidor del Model Context Protocol (MCP) de alto rendimiento para las APIs REST de MapmyIndia (Mappls), construido con el framework de código abierto FastMCP.

Este servidor permite que asistentes de IA (como Claude, Gemini, ChatGPT, Cursor y Antigravity) consulten datos geográficos, realicen geocodificación, generen indicaciones de conducción y caminata, calculen ETAs de matrices de distancia, descubran puntos de interés (POIs) y consulten detalles de lugares mediante códigos eLoc en toda India.

Características

• Framework FastMCP: Construido sobre el framework Python fastmcp de Prefect HQ para generación automática de esquemas, validación robusta y baja latencia.

• Autenticación flexible:

  • Modo de token de acceso estático: Pasa un MAPPLS_ACCESS_TOKEN bearer directo.

  • Flujo de credenciales de cliente OAuth 2.0: Pasa MAPPLS_CLIENT_ID y MAPPLS_CLIENT_SECRET para la generación automática de tokens y su renovación antes de la expiración.

• Herramientas completas de Mappls:

  • mappls_geocode: Convierte nombres de lugares en coordenadas lat/long y códigos eLoc.

  • mappls_reverse_geocode: Convierte coordenadas en detalles de dirección.

  • mappls_autosuggest: Sugerencias de búsqueda de ubicación predictivas en vivo.

  • mappls_get_directions: Indicaciones de ruta (conducción, caminata, bicicleta, camión) con pasos paso a paso.

  • mappls_distance_matrix: Cálculo de matrices de tiempo y distancia de N a M.

  • mappls_snap_to_road: Ajusta rastros de coordenadas GPS ruidosos a redes viales.

  • mappls_search_nearby: Descubre POIs (restaurantes, cajeros automáticos, hospitales, cargadores para vehículos eléctricos, estaciones de combustible) en las cercanías.

  • mappls_place_details: Obtiene atributos enriquecidos para cualquier código eLoc de 6 caracteres de Mappls.

  • mappls_text_search: Búsqueda inteligente de lugares con corrección ortográfica.

• Prompts MCP integrados: Plantillas preconfiguradas como plan_itinerary y optimize_logistics_hub.

• Soporte de doble transporte: Ejecutar vía stdio (para aplicaciones de escritorio) o sse (para microservicios HTTP).

• Modo sin conexión / simulación: Se ejecuta sin problemas en modo de prueba cuando no se proporcionan claves de API.

Instalación y configuración

1. Requisitos

• Python 3.10 o superior

• Credenciales de desarrollador de MapmyIndia (Mappls) o token de acceso (desde Mappls Console)

2. Configuración del entorno

Clona o copia este repositorio y luego crea un archivo .env a partir de .env.example:

cp .env.example .env

Edita .env y completa tu token de Mappls o tus credenciales de cliente:

# Option A: Direct Access Token (Recommended for Token Input)
MAPPLS_ACCESS_TOKEN=your_access_token_here

# Option B: Client Credentials
MAPPLS_CLIENT_ID=your_client_id_here
MAPPLS_CLIENT_SECRET=your_client_secret_here

MCP_TRANSPORT=stdio

3. Instalar el paquete

Instala el paquete en modo editable:

pip install -e .

O instala con dependencias de desarrollo:

pip install -e ".[dev]"

Configuración rápida para cualquiera (ejecutar con uvx directamente desde GitHub)

Cualquier persona puede usar este servidor MCP directamente desde GitHub sin clonar el repositorio ni instalar localmente usando uvx (incluido con uv).

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "mappls": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Bhupendrajee07/MMI-MCP.git",
        "mmi-mcp"
      ],
      "env": {
        "MAPPLS_CLIENT_ID": "YOUR_MAPPLS_CLIENT_ID",
        "MAPPLS_CLIENT_SECRET": "YOUR_MAPPLS_CLIENT_SECRET"
      }
    }
  }
}

2. Antigravity / Cursor / VS Code (mcp_config.json)

{
  "mcpServers": {
    "mappls": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Bhupendrajee07/MMI-MCP.git",
        "mmi-mcp"
      ],
      "env": {
        "MAPPLS_ACCESS_TOKEN": "YOUR_MAPPLS_ACCESS_TOKEN"
      }
    }
  }
}

Desarrollo y uso local

Ejecutar vía Stdio (por defecto)

mmi-mcp
# or
python -m mmi_mcp.server --transport stdio

Ejecutar vía SSE (servidor HTTP)

python -m mmi_mcp.server --transport sse --host 127.0.0.1 --port 8000

Ejecución de pruebas

Ejecuta la suite de pruebas unitarias y de integración:

$env:PYTHONPATH="src"; python -m pytest tests/ -v

Licencia

Licencia MIT