内容
<p align="center">
<img src="assets/logo.svg" alt="谷歌地图 MCP 服务器 — 红色地图图标与 MCP 徽章" width="160"/>
</p>
# 谷歌地图 MCP 服务器
[](https://pypi.org/project/gmaps-mcp/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
`gmaps-mcp` 是一个 **MCP 服务器,为 Claude Desktop、Cursor 和 Claude Code 提供完整的谷歌地图功能** — 包括地点搜索、地点详情、附近搜索、路线规划、地理编码和反向地理编码。只需一行命令安装 (`uvx gmaps-mcp`),在 MCP 客户端中添加一个配置块,您的 AI 助手就可以原生调用谷歌地图。
本项目基于官方 [模型上下文协议](https://modelcontextprotocol.io) Python SDK 和 FastMCP。支持 **stdio 传输**(适用于本地 Claude Desktop / Cursor)和 **可流式 HTTP 传输**(适用于远程部署和 A2A 代理到代理场景)。
<!-- TODO: 记录 15 秒演示 GIF,展示 Claude Desktop 使用 search_places,并将其放在此处 -->
## 安装后您可以向 Claude 提问的内容
- "在旧金山找到附近的特色咖啡店"
- "在东京涩谷有哪些评价好的拉面店?"
- "从联合广场到渡轮大楼步行需要多长时间?"
- "提供从 SFO 到伯克利的驾驶路线"
- "埃菲尔铁塔的坐标是什么?"
- "37.8199, -122.4783 的地址是什么?"
- "在这些坐标周围 2 公里范围内找到一家 24 小时药店"
- "显示北滩地区评分最高的意大利餐厅及其营业时间和电话号码"
MCP 客户端会自动选择合适的工具 — 您无需指定工具名称。
## 在 Claude Desktop 中安装
编辑您的 `claude_desktop_config.json`(设置 → 开发者 → 编辑配置)并添加:
```json
{
"mcpServers": {
"google-maps": {
"command": "uvx",
"args": ["gmaps-mcp"],
"env": {
"GOOGLE_MAPS_API_KEY": "您的谷歌地图 API 密钥"
}
}
}
}
```
重启 Claude Desktop。`uvx`会在首次运行时从 PyPI 获取 `gmaps-mcp` 并缓存它 — 无需克隆,无需虚拟环境,无需 Docker。
## 在 Cursor 中安装
编辑 `~/.cursor/mcp.json` 并添加:
```json
{
"mcpServers": {
"google-maps": {
"command": "uvx",
"args": ["gmaps-mcp"],
"env": {
"GOOGLE_MAPS_API_KEY": "您的谷歌地图 API 密钥"
}
}
}
}
```
重启 Cursor。完成。
## 在 Claude Code 中安装
在终端中运行一条命令:
```bash
claude mcp add google-maps \
-e GOOGLE_MAPS_API_KEY=您的谷歌地图_API密钥 \
-- uvx gmaps-mcp
```
使用 `claude mcp list` 确认。
## 获取谷歌地图 API 密钥
您需要一个谷歌地图平台 API 密钥,并启用 **新版地点 API**、**路线 API** 和 **地理编码 API**。这只需 3 分钟。谷歌提供 **每月 200 美元的免费地图积分**,远远超过个人或小型团队的使用量。
### 步骤
1. 前往 [谷歌云控制台](https://console.cloud.google.com/) 并创建(或选择)一个项目。
2. **启用项目的计费**。即使是免费层也需要此步骤。如果跳过此步骤,每个谷歌地图调用都将返回 `403 BILLING_DISABLED`(请参阅[故障排除](#故障排除))。添加一张卡 — 免费积分先用,您不会为正常使用付费。
3. 在 **API 和服务 → 库** 中启用以下 API:
- **新版地点 API** — 支持 `search_places`、`get_place_details`、`search_nearby`
- **路线 API** — 支持 `get_directions`
- **地理编码 API** — 支持 `geocode`、`reverse_geocode`
4. 前往 **API 和服务 → 凭证 → + 创建凭证 → API 密钥**。
5. (推荐)点击新密钥 → **编辑** → **API 限制** → 限制为仅这三个 API。
6. 将密钥复制到上面的 MCP 客户端配置中。
## 工具
所有六种工具都是针对实时数据的真实谷歌地图调用。没有模拟,没有存根响应。
| 工具 | 功能 |
|---|---|
| [`search_places`](#search_places) | 基于自然语言查询的地点文本搜索 |
| [`get_place_details`](#get_place_details) | 获取特定地点的评论、设施、营业时间、电话和价格级别 |
| [`search_nearby`](#search_nearby) | 在 GPS 坐标的半径范围内查找地点,按类型过滤 |
| [`get_directions`](#get_directions) | 两地之间的分步路线 — 驾驶、步行、骑行、公共交通 |
| [`geocode`](#geocode) | 地址或地标 → GPS 坐标 |
| [`reverse_geocode`](#reverse_geocode) | GPS 坐标 → 人类可读地址 |
### `search_places`
基于自然语言查询的地点文本搜索。返回带有评分、地址、电话号码、网站、营业时间和坐标的商家、地标和兴趣点。
**向 Claude 提问:**
- "在旧金山找到特色咖啡店"
- "在涩谷最好的拉面店"
- "布鲁克林的 24 小时药店"
- "金门公园附近的宠物友好咖啡馆"
**返回:** `query`、`total_results`、`places[]` 包含 `name`、`address`、`phone`、`website`、`google_maps_url`、`rating`、`reviews_count`、`price_level`、`types`、`latitude`、`longitude`、`is_open_now`、`opening_hours`、`business_status`。
### `get_place_details`
使用谷歌地点 ID(由 `search_places` 返回)获取特定地点的详细信息。包括评论、设施、编辑摘要和付款选项。
**向 Claude 提问:**
- "显示第一个咖啡店的评论"
- "第二个餐厅是否适合带狗?他们有户外座位吗?"
- "我刚刚询问的地点营业时间和电话号码是多少"
**返回:** `search_places` 返回的所有内容,加上前 5 条 `reviews`(作者、评分、文本、相对时间)、`editorial_summary` 和设施标志:`delivery`、`dine_in`、`takeout`、`reservable`、`outdoor_seating`、`live_music`、`payment_options`、`accessibility_options`。
### `search_nearby`
在特定 GPS 坐标的半径范围内查找地点。在使用 `geocode` 获取位置后,或用户直接提供坐标时使用。
**向 Claude 提问:**
- "在这些坐标周围 500 米内找到咖啡馆"
- "埃菲尔铁塔周围 2 公里范围内有哪些酒店?"
- "在 37.7955, -122.3937 周围 5 公里内显示加油站"
**参数:** `latitude`、`longitude`、`radius_meters`(最大 50,000)、`place_type`(可选 — `restaurant`、`cafe`、`bar`、`hotel`、`gas_station`、`pharmacy`、`hospital` 等)、`max_results`。
**返回:** `center`、`radius_meters`、`place_type`、`total_results`、`places[]` 包含与 `search_places` 相同的内容。
### `get_directions`
两地之间的分步导航,包含总距离和时长。支持驾驶(含交通-aware 时长)、步行、骑行和公共交通。
**向 Claude 提问:**
- "我如何从联合广场步行到渡轮大楼?"
- "给我从 SFO 到伯克利的驾驶路线,考虑交通情况"
- "从中央公园到时代广场骑自行车路线"
**参数:** `origin`(地址、地标或 `"lat,lng"`)、`destination`(相同)、`mode`(`"driving"` 默认、`"walking"`、`"bicycling"`、`"transit"`)。
**返回:** `origin`、`destination`、`mode`、`routes[]` 包含 `summary`、`legs[]` 包含 `start_address`、`end_address`、`distance`、`duration`、`duration_in_traffic` 和 `steps[]` 包含分步 `instruction`、`distance`、`duration`。
### `geocode`
将地址、地标或地点描述转换为 GPS 坐标。
**向 Claude 提问:**
- "埃菲尔铁塔的坐标是什么?"
- "地理编码 1600 Amphitheatre Parkway, Mountain View"
- "旧金山渡轮大楼的经纬度是多少?"
**返回:** `query`、`formatted_address`、`latitude`、`longitude`、`place_id`、`location_type`、`types`。
### `reverse_geocode`
将 GPS 坐标转换为人类可读的地址。
**向 Claude 提问:**
- "37.8199, -122.4783 处是什么?"
- "反向地理编码这些坐标:48.8584, 2.2945"
- "纬度 40.7580,经度 -73.9855 的地址是什么?"
**返回:** `latitude`、`longitude`、`formatted_address`、`place_id`、`address_components[]`。
## 故障排除
### 来自 Google 的 `403 BILLING_DISABLED` / `403 Forbidden`
这是最常见的设置问题。错误如下所示:
```
Google Maps API 错误:403 - {
"error": {
"code": 403,
"message": "此 API 方法需要启用计费...",
"status": "PERMISSION_DENIED",
"details": [{"reason": "BILLING_DISABLED", ...}]
}
}
```
**解决方法:** 返回 [API 密钥设置的步骤 2](#获取谷歌地图-API-密钥) 并在 GCP 项目上启用计费。即使您永远不会为正常个人使用付费(谷歌的每月 200 美元免费积分涵盖),也需要启用计费。**请等待 2-3 分钟**,让更改在谷歌系统中生效,然后重试。
### `API_KEY_INVALID` / `API 项目未授权`
您已启用计费,但忘记启用特定 API。返回 [步骤 3](#获取谷歌地图-API-密钥) 并分别启用新版地点 API、路线 API 和地理编码 API。
### `uvx: command not found`
首先安装 [`uv`](https://docs.astral.sh/uv/):`curl -LsSf https://astral.sh/uv/install.sh | sh`(macOS/Linux)或 `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`(Windows)。
### 工具在 HTTP 模式下工作,但在 stdio 模式下不工作(或反之)
两种传输方式共享相同的客户端和工具实现 — 如果一种方式有效,另一种方式也应该有效。如果您遇到不匹配的情况,请提交问题并附上错误输出。
## 为什么使用此 MCP 服务器
如果您在 PyPI 上搜索谷歌地图 MCP 服务器,您会发现几个选项。以下是 `gmaps-mcp` 的不同之处:
- **一个软件包中的两种传输方式。** 支持 stdio 传输(适用于本地使用)和可流式 HTTP 传输(适用于远程部署和 A2A 场景)。相同的代码库、相同的工具、相同的行为。
- **所有六种谷歌地图功能。** 不仅仅是搜索 — 还有地点详情、附近搜索、含交通信息的路线、地理编码、反向地理编码。
- **使用新版地点 API。** 当前的谷歌地点 API,而不是谷歌已弃用的旧版 v1 端点。
- **真正的 FastMCP 实现。** 构建在官方 MCP Python SDK 之上,而不是手写的协议解析器。
- **MIT 许可,无遥测。** 您的查询不会离开您的机器,除非直接调用谷歌的 API。
- **针对真实 API 进行测试。** 每个工具都在两种传输方式下针对实时谷歌端点进行端到端验证。
## 远程 HTTP 服务器模式
对于部署、共享团队使用或 A2A 代理到代理场景,`gmaps-mcp` 也作为可流式 HTTP 服务器运行,支持可选的 API 密钥身份验证。
```bash
git clone https://github.com/arthurkatcher/google-maps-mcp
cd google-maps-mcp
uv sync
cp .env.example .env # 编辑您的 API 密钥
python run.py
```
服务器默认监听 `http://127.0.0.1:8000`,MCP 端点在 `/mcp/`,健康检查在 `/health`。对于仅限本地使用,您可以不设置 `MCP_API_KEY`。
> ⚠️ **在公网上公开服务器之前**(ngrok、反向代理、局域网等):设置 `MCP_API_KEY` 为随机密钥。没有它,任何到达 URL 的人都可以运行与您的付费 `GOOGLE_MAPS_API_KEY` 相关的搜索。还请绑定到 `127.0.0.1`,让您的隧道/代理从那里转发,而不是绑定到 `0.0.0.0`。
```bash
# .env
MCP_API_KEY=$(openssl rand -hex 32)
MCP_HOST=127.0.0.1
# 然后
python run.py
ngrok http 8000 --host-header=rewrite
# 客户端使用 X-API-Key: <密钥> 调用 https://your-ngrok-url.ngrok-free.dev/mcp/
```
> ℹ️ **为什么使用 `--host-header=rewrite`。** MCP Python SDK 的 HTTP 传输验证 `Host` 头部以防止针对本地服务器的 DNS 重新绑定攻击。ngrok 的默认转发公共主机名,SDK 拒绝 `421 无效主机头`。`--host-header=rewrite` 使 ngrok 转发上游 `Host`(`127.0.0.1:8000`),通过检查。相同的推理适用于其他隧道和反向代理 — 设置上游 `Host` 为您的绑定地址。
### 安全考虑
当您在 HTTP 上运行 `gmaps-mcp` 时,请将 `MCP_API_KEY` 视为一个凭证,它控制一个付费的谷歌云账户。一些运营商级别的默认设置值得注意:
- **在密钥疑似泄露时轮换密钥。** 它是一个环境变量;将密钥粘贴到截图、提交的日志或共享会话中就足以泄露它。
- **在包含您的 `GOOGLE_MAPS_API_KEY` 的 GCP 项目上设置谷歌云计费警报。** 选择一个阈值远低于您一周内可能遭受的损失的数值。这是廉价的备份措施,防止任何泄露 — 您的密钥、MCP 密钥或第三方抓取隧道 URL。
- **将谷歌地图 API 密钥限制为仅 `gmaps-mcp` 使用的三个 API**,在 *API 和服务 → 凭证 → 编辑* 下。或者,将其固定到您的家庭/服务器 IP 以增加安全性。
- **暂时没有服务器端速率限制。** 泄露的 `MCP_API_KEY` 允许攻击者以其带宽允许的最大速度烧毁配额。在此功能实现之前,计费警报是您的断路器。
- **不要在未设置密钥的情况下公开 `MCP_HOST=0.0.0.0`。** 如果您这样做,服务器会拒绝启动(此功能在 0.1.3+ 中强制实施 — 一个刻意的防护措施,在 [GHSA-52cq-7v8r-62c6][1] 之后添加)。
[1]: https://github.com/arthurkatcher/google-maps-mcp/security/advisories/GHSA-52cq-7v8r-62c6
## 定价
谷歌地图平台提供 **每月 200 美元的免费积分**,可覆盖大致:
- ~11,000 次新版地点 API 请求,或
- ~40,000 次地理编码 API 请求,或
- ~40,000 次路线 API 请求。
对于个人或小型团队使用,您几乎永远不会达到上限。在免费层之外,预计每 1,000 次地点请求大约 17 美元,每 1,000 次地理编码/路线请求大约 5 美元。请参阅 [谷歌地图平台定价](https://developers.google.com/maps/billing-and-pricing/pricing) 以获取当前费率。
## 开发
```bash
git clone https://github.com/arthurkatcher/google-maps-mcp
cd google-maps-mcp
uv sync
cp .env.example .env # 添加您的真实 API 密钥
# 在 stdio 模式下运行(适用于本地 MCP 客户端)
uv run python -m google_maps_mcp
# 在 HTTP 模式下运行(适用于远程客户端)
uv run python run.py
```
## 路线图
- **地点 API v2 字段** — 利用谷歌推出的新评论/媒体字段
- **交通感知 ETA 工具** — 专门的实时交通工具
- **地点照片** — 提取 `PlacePhoto` URL 用于 UI 渲染
- **静态地图渲染** — 为地点或路线返回静态地图图像的工具
- **自动完成建议** — 在 MCP 服务器上构建基于顶层的 UI
- **MCP 注册表提交** — 在 [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) 上稳定后进行列表
## 项目结构
```
google-maps-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── run.py # HTTP 服务器入口点
└── src/google_maps_mcp/
├── __init__.py
├── __main__.py # stdio 服务器入口点
├── client.py # 谷歌地图 API 客户端
├── tools.py # 工具包装器
└── server.py # FastMCP 服务器 + Starlette HTTP 中间件
```
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。在任何地方使用它,fork 它,发布它。
## 致谢
由 [Arthur Katcher](https://github.com/arthurkatcher) 构建。欢迎贡献、错误报告和 PR,位于 [github.com/arthurkatcher/google-maps-mcp](https://github.com/arthurkatcher/google-maps-mcp)。如果此 MCP 服务器为您节省了时间,我要求的唯一回报是一颗 GitHub 星。