MapmyIndia (Mappls) MCP Server (FastMCP)

A high-performance Model Context Protocol (MCP) server for MapmyIndia (Mappls) REST APIs, built using the FastMCP open-source framework.

This server enables AI assistants (such as Claude, Gemini, ChatGPT, Cursor, and Antigravity) to query geographic data, perform geocoding, generate driving & walking directions, calculate distance matrix ETAs, discover points of interest (POIs), and look up eLoc place details across India.

---

Features

• FastMCP Framework: Built on Prefect HQ's fastmcp Python framework for automatic schema generation, robust validation, and low latency.
• Flexible Authentication:
  • Static Access Token Mode: Pass a direct bearer MAPPLS_ACCESS_TOKEN.
  • OAuth 2.0 Client Credentials Flow: Pass MAPPLS_CLIENT_ID and MAPPLS_CLIENT_SECRET for automated token generation and pre-expiry refreshing.
• Comprehensive Mappls Tools:
  • mappls_geocode: Convert location names to lat/long coordinates & eLoc codes.
  • mappls_reverse_geocode: Convert coordinates to formatted address details.
  • mappls_autosuggest: Live predictive location search suggestions.
  • mappls_get_directions: Route directions (driving, biking, walking, trucking) with turn-by-turn steps.
  • mappls_distance_matrix: N-to-M travel time and distance matrix calculations.
  • mappls_snap_to_road: Snap noisy GPS coordinate traces to road networks.
  • mappls_search_nearby: Discover POIs (restaurants, ATMs, hospitals, EV chargers, fuel stations) nearby.
  • mappls_place_details: Retrieve rich attributes for any 6-character Mappls eLoc code.
  • mappls_text_search: AI smart place search with spelling correction.
• Built-in MCP Prompts: Pre-configured templates like plan_itinerary and optimize_logistics_hub.
• Dual Transport Support: Run via stdio (for desktop apps) or sse (for HTTP microservices).
• Offline / Mock Mode: Runs seamlessly in dry-run mode when API keys are not provided.

---

Installation & Setup

1. Requirements

• Python 3.10 or higher
• MapmyIndia (Mappls) Developer Credentials or Access Token (from Mappls Console)

2. Environment Configuration

Clone or copy this repository, then create a .env file from .env.example:

cp .env.example .env

Edit .env and fill in your Mappls token or client credentials:

# 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. Install Package

Install the package in editable mode:

pip install -e .

Or install with development dependencies:

pip install -e ".[dev]"

---

Quick Setup for Anyone (Run via uvx directly from GitHub)

Anyone can use this MCP server directly from GitHub without cloning or local installation by using uvx (included with 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"
      }
    }
  }
}

---

Local Development & Usage

Run via Stdio (Default)

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

Run via SSE (HTTP Server)

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

---

Running Tests

Run the unit and integration test suite:

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

---

License

MIT License