MapmyIndia (Mappls) MCP Server (FastMCP)

Ein Hochleistungs-Model-Context-Protocol-Server (MCP) für die MapmyIndia (Mappls) REST-APIs, basierend auf dem Open-Source-Framework FastMCP.

Dieser Server ermöglicht es KI-Assistenten (wie Claude, Gemini, ChatGPT, Cursor und Antigravity), geografische Daten abzufragen, Geocoding durchzuführen, Fahr- und Geh-Routen zu erstellen, ETAs für Distanzmatrizen zu berechnen, Points of Interest (POIs) zu entdecken und eLoc-Ortsdetails in ganz Indien nachzuschlagen.

Funktionen

• FastMCP-Framework: Basierend auf dem fastmcp-Python-Framework von Prefect HQ für automatische Schema-Generierung, robuste Validierung und geringe Latenz.

• Flexible Authentifizierung:

  • Statischer Access-Token-Modus: Direktes Bearer-MAPPLS_ACCESS_TOKEN übergeben.

  • OAuth-2.0-Client-Credentials-Flow: MAPPLS_CLIENT_ID und MAPPLS_CLIENT_SECRET übergeben für automatische Token-Generierung und Aktualisierung vor Ablauf.

• Umfassende Mappls-Tools:

  • mappls_geocode: Konvertiert Ortsnamen in Breiten-/Längengrad-Koordinaten und eLoc-Codes.

  • mappls_reverse_geocode: Konvertiert Koordinaten in formatierte Adressdetails.

  • mappls_autosuggest: Live-Vorhersagevorschläge für die Ortssuche.

  • mappls_get_directions: Routenführung (Auto, Fahrrad, zu Fuß, LKW) mit Abbiegehinweisen Schritt für Schritt.

  • mappls_distance_matrix: Berechnung von Reisezeit- und Distanzmatrizen von N zu M.

  • mappls_snap_to_road: Gleicht verrauschte GPS-Koordinatenspuren an Straßennetze an.

  • mappls_search_nearby: Entdeckt Points of Interest (POIs) in der Nähe (Restaurants, Geldautomaten, Krankenhäuser, E-Ladestationen, Tankstellen).

  • mappls_place_details: Ruft umfangreiche Attribute für jeden 6-stelligen Mappls-eLoc-Code ab.

  • mappls_text_search: Intelligente KI-Ortssuche mit Rechtschreibkorrektur.

• Integrierte MCP-Prompts: Vorkonfigurierte Vorlagen wie plan_itinerary und optimize_logistics_hub.

• Unterstützung für zwei Transportarten: Ausführung über stdio (für Desktop-Apps) oder sse (für HTTP-Mikrodienste).

• Offline-/Mock-Modus: Läuft nahtlos im Trockenlauf-Modus, wenn keine API-Schlüssel angegeben werden.

Installation & Einrichtung

1. Voraussetzungen

• Python 3.10 oder höher

• MapmyIndia (Mappls)-Entwickleranmeldedaten oder Access-Token (von der Mappls-Konsole)

2. Umgebungskonfiguration

Klonen oder kopieren Sie dieses Repository und erstellen Sie dann eine .env-Datei aus .env.example:

cp .env.example .env

Bearbeiten Sie .env und tragen Sie Ihr Mappls-Token oder Ihre Client-Anmeldedaten ein:

# 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. Paket installieren

Installieren Sie das Paket im bearbeitbaren Modus (editable mode):

pip install -e .

Oder installieren Sie es mit Entwicklungsabhängigkeiten:

pip install -e ".[dev]"

Schnelleinrichtung für alle (Ausführung über uvx direkt von GitHub)

Jeder kann diesen MCP-Server direkt von GitHub nutzen, ohne Klonen oder lokale Installation, mithilfe von uvx (im Lieferumfang von uv enthalten).

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"
      }
    }
  }
}

Lokale Entwicklung & Nutzung

Ausführung über Stdio (Standard)

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

Ausführung über SSE (HTTP-Server)

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

Tests ausführen

Führen Sie die Unit- und Integrationstests aus:

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

Lizenz

MIT-Lizenz