MapmyIndia (Mappls) MCP Server (FastMCP)

一个面向 MapmyIndia (Mappls) REST API 的高性能 Model Context Protocol (MCP) 服务器，基于 FastMCP 开源框架构建。

该服务器使 AI 助手（如 Claude、Gemini、ChatGPT、Cursor 和 Antigravity）能够查询地理数据、执行地理编码、生成驾车和步行路线、计算距离矩阵 ETA、发现兴趣点（POI），并查询印度各地的 eLoc 地点详情。

功能特性

• FastMCP 框架：基于 Prefect HQ 的 fastmcp Python 框架构建，支持自动 schema 生成、稳健的验证和低延迟。

• 灵活的身份验证：

  • 静态访问令牌模式：直接传入 bearer MAPPLS_ACCESS_TOKEN。

  • OAuth 2.0 客户端凭证流程：传入 MAPPLS_CLIENT_ID 和 MAPPLS_CLIENT_SECRET，实现令牌自动生成和过期前自动刷新。

• 全面的 Mappls 工具：

  • mappls_geocode：将地点名称转换为经纬度坐标和 eLoc 代码。

  • mappls_reverse_geocode：将坐标转换为格式化的地址详情。

  • mappls_autosuggest：实时预测性地点搜索建议。

  • mappls_get_directions：路线导航（驾车、骑行、步行、卡车），提供逐向步骤。

  • mappls_distance_matrix：N 对 M 的出行时间和距离矩阵计算。

  • mappls_snap_to_road：将带有噪声的 GPS 坐标轨迹匹配到道路网络。

  • mappls_search_nearby：发现附近的兴趣点（餐厅、ATM、医院、电动汽车充电桩、加油站）。

  • mappls_place_details：检索任意 6 位 Mappls eLoc 代码的丰富属性。

  • mappls_text_search：支持拼写纠正的 AI 智能地点搜索。

• 内置 MCP 提示词（Prompts）：预配置的模板，如 plan_itinerary 和 optimize_logistics_hub。

• 双传输支持：可通过 stdio（适用于桌面应用）或 sse（适用于 HTTP 微服务）运行。

• 离线 / 模拟模式：未提供 API 密钥时，可在 dry-run 模式下无缝运行。

安装与设置

1. 环境要求

• Python 3.10 或更高版本

• MapmyIndia (Mappls) 开发者凭证或访问令牌（来自 Mappls Console）

2. 环境配置

克隆或复制此仓库，然后根据 .env.example 创建 .env 文件：

cp .env.example .env

编辑 .env 并填写你的 Mappls 令牌或客户端凭证：

# 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. 安装包

以可编辑模式安装该包：

pip install -e .

或安装包含开发依赖的版本：

pip install -e ".[dev]"

面向所有人的快速设置（通过 uvx 直接从 GitHub 运行）

任何人都可以通过 uvx（随 uv 附带）直接从 GitHub 使用此 MCP 服务器，无需克隆或本地安装。

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

本地开发与使用

通过 Stdio 运行（默认）

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

通过 SSE 运行（HTTP 服务器）

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

运行测试

运行单元测试和集成测试套件：

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

许可证

MIT License