Google Maps MCP 服务器

使用说明（Markdown 格式）

项目概览

• 这是一个基于 Model Context Protocol (MCP) 的后端服务器，专门把 Google Maps Platform 的功能暴露为可通过 MCP 客户端调用的工具集合，进而为 LLM 应用提供结构化的地图数据、路线计算和地点信息等上下文能力。

主要功能点

• 提供 15 个工具，覆盖三个分类：
  • 地图（Maps）：静态地图 URL、嵌入 URL、海拔、Street View 等
  • 路线（Routes）：驾车/步行/自行车/公共交通的逐步导航、距离矩阵、多点优化等
  • 地点（Places）：地理编码、地点详情、文本搜索、周边搜索、自动完成、照片、地址校验、时区等
• 传输与会话
  • 基于 MCP SDK 的流式 HTTP 传输（Streamable HTTP Transport），支持状态化会话和 Keep-alive
  • 会话通过 Mcp-Session-Id 进行管理，具备会话清理与容量控制
  • 通过 X-Api-Key 进行服务端认证，约束后端访问
• 数据源与安全
  • 所有 Google Maps 调用使用 REST API，直接通过 Node.js fetch 实现，无需额外的 Google SDK
  • 旧版 API 使用 key 参数，新版 API 使用 X-Goog-Api-Key 头部进行鉴权
• 部署与运行
  • 提供本地、Docker、以及构建自源代码的多种运行方式
  • 公开健康接口 /health，MCP 端点 /mcp，便于集成到现有 MCP 客户端工作流
• 客户端连接示例
  • 官方 README 中给出与 Claude Desktop/其他 MCP 客户端的对接方式，示例包含使用 mcp-remote 的启动参数与必要的 API key 头部

安装步骤（简要）

• 确保环境
  • Node.js 22 及以上（可用 Docker 运行）
  • Google Maps Platform API Key（具备所需 API 的权限）
  • Google Cloud 项目并开启账单
• 基本本地运行
  • 克隆仓库并安装依赖
  • 设置 GOOGLE_MAPS_API_KEY 与 MCP_AUTH_TOKEN 环境变量
  • 启动服务器
• 生产化运行
  • 使用 Docker 或 Docker Compose 进行部署
  • 持续监控健康情况与会话状态

服务器配置（给 MCP 客户端的连接信息，JSON 格式描述） { "serverName": "google-maps-mcp", "command": "npx", "args": [ "mcp-remote", "http://localhost:3003/mcp", "--header", "X-Api-Key: <YOUR_MCP_TOKEN>" ], "description": "用于 MCP 客户端连接的启动信息，需替换 <YOUR_MCP_TOKEN> 为实际的 MCP 认证令牌。服务器端会对 X-Api-Key 进行校验，未提供或不匹配将拒绝连接。" }

基本使用方法

• 启动前准备
  • 将 GOOGLE_MAPS_API_KEY 设置为一个有效的 Google Maps API Key
  • 将 MCP_AUTH_TOKEN 设置为客户端连接时需要使用的令牌
• 启动服务器
  • 以 Docker 或本地 Node.js 环境启动
• 客户端连接步骤（MCP 客户端需要提供以下信息才能建立连接）
  • 指定服务器名称为 google-maps-mcp
  • 使用命令与参数启动 mcp-remote 客户端，目标地址为 http://localhost:3003/mcp
  • 在请求中加入头部 X-Api-Key，值为实际的 MCP_TOKEN
• 使用流程
  • 客户端对服务器执行 initialize 初始化，设定协议版本等能力
  • 根据需求调用工具，如 maps_static_map、routes_compute、places_geocode 等
  • 读取工具输出的内容，进行后续对话上下文的构建与渲染
• 运行提示
  • 默认端口 3003，可通过 PORT 环境变量覆盖
  • 支持通过 Docker Compose 部署，结合环境变量注入 API Key 与 Token