/ 目录 / 演练场 / Google Maps
● 官方 modelcontextprotocol 🔑 需要你的密钥

Google Maps

作者 modelcontextprotocol · modelcontextprotocol/servers-archived

地理编码、地点搜索、路线导航、距离矩阵 — Google Maps 的强大功能,适用于行程规划、门店定位和区域分析。

参考级的 Google Maps MCP(现已归档到 modelcontextprotocol/servers-archived)。封装了关键的 Maps API:地理编码、地点搜索和详情、路线导航、距离矩阵、高程查询。适合任何需要真实地理数据的 agent 任务。注意:已归档意味着没有主动维护 — 长期来看要为社区 fork 做好准备。

为什么要用

核心特性

实时演示

实际使用效果

google-maps.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-google-maps"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-google-maps"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-google-maps"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-google-maps"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "google-maps",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-google-maps"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "google-maps": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-google-maps"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add google-maps -- npx -y @modelcontextprotocol/server-google-maps

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Google Maps

规划一次真实的一日游行程,考虑实际的驾车时间

👤 旅行者,任何规划多站一日游的人 ⏱ ~10 min beginner

何时使用: 你想在一天内去5个地方,需要一个现实的顺序安排和驾车时间。

前置条件
  • 启用了相关 API 的 Google Maps API key — console.cloud.google.com → 启用 Geocoding、Places、Directions API,然后创建 key
步骤
  1. 对所有站点进行地理编码
    对这5个地点进行地理编码,转换为经纬度:<list>。验证每个地址看起来没问题。✓ 已复制
    → 5个坐标,置信度高
  2. 计算距离矩阵
    获取工作日上午10点时,所有站点对之间的驾车时间。以矩阵形式展示。✓ 已复制
    → 5×5 时间矩阵
  3. 排序并添加路线导航
    建议能最小化总驾车时间的顺序。然后给我从站点到站点的转向导航。✓ 已复制
    → 优化后的路线,带有导航指令

结果: 一个你真的能执行的行程,不是『听起来不错』的规划。

注意事项
  • 距离矩阵不计入停车时间/走到门口的时间 — 每段路程加上10-15分钟的停车时间;市中心目的地可能需要更久
  • 实时交通仅在某些模式/地区可用 — 使用 departure_time 获取考虑实时交通的估计;根据你的套餐,'now'可能被排除
搭配使用: brave-search

为区域产品构建门店定位器数据

👤 正在实现『查找门店』功能的开发者 ⏱ ~30 min intermediate

何时使用: 你在构建『最近的门店』功能,需要用真实的坐标和详情来初始化。

步骤
  1. 对每个门店地址进行地理编码
    我有一份50个门店地址的CSV文件在 /data/stores.csv。对每个进行地理编码,返回一份新CSV,添加 lat、lng、place_id 和 Google 标准化后的地址。✓ 已复制
    → 丰富化的CSV;标记任何没有干净地理编码的地址
  2. 拉取每个地点的详细信息
    对于每个 place_id,获取营业时间、电话、网站。添加到CSV。✓ 已复制
    → 每家门店的详情,缺失数据的地方有标记
  3. 验证样本
    随机抽取5行,验证地理编码的坐标看起来在正确的位置(比如『斯德哥尔摩的地址编码到瑞典,而不是威斯康辛州』)。✓ 已复制
    → 健全性检查通过;异常值标记

结果: 一份干净的门店数据集,已准备好驱动UI。

注意事项
  • 地理编码 API 按次计费 — 50个地址只需几美分,但50k就是真金白银了 — 积极地缓存结果;仅在地址字符串改变时重新地理编码
搭配使用: filesystem

找出你有多少客户住在候选地点的X分钟车程内

👤 运营、房地产、增长分析师 ⏱ ~25 min advanced

何时使用: 你在评估一个新的门店/办公室位置,想知道它能服务多少现有客户。

步骤
  1. 地理编码候选地点
    地理编码这个候选地址:'1234 Market St, San Francisco'。✓ 已复制
    → 坐标确认
  2. 距离矩阵到客户邮编
    从候选地点,计算到这100个客户邮编中心点的驾车时间:<list>。使用工作日上午9点。✓ 已复制
    → 每个邮编的驾车时间
  3. 汇总
    有多少客户在15分钟、30分钟、60分钟内?绘制一个直方图(ASCII条形图也行)。✓ 已复制
    → 分桶的计数,能帮助决策

结果: 一个数据驱动的『我们应该在这里开张吗?』的答案。

注意事项
  • 邮编中心点是实际客户地址的代理,效果不理想 — 如果你有实际地址,就用它们;中心点会扭曲郊区的分析
  • 距离矩阵限制批量大小 — Google 限制每次调用的出发地×目的地数量;分成多次请求,但无论如何你都是按元素付费
搭配使用: postgres · filesystem

组合

与其他 MCP 搭配,撬动十倍杠杆

google-maps + filesystem

批量地理编码CSV并将丰富化的文件写回

读取 /data/customers.csv,对每个地址进行地理编码,将 /data/customers_geo.csv 写入已添加 lat/lng/place_id 列的内容。✓ 已复制
google-maps + postgres

在客户入职时对客户行进行地理编码

customers 表中每一行,其中 lat IS NULL,对地址进行地理编码并更新该行。停止于500条来控制成本。✓ 已复制
google-maps + brave-search

Brave 搜索找到候选地点 → Google Maps 获取地理编码 + 路线导航

Brave 搜索『最好的拉面店 Mission SF』。对前3个,获取 place_id 和从 16th St BART 的步行路线。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
maps_geocode address: str 地址 → 坐标 $5 / 1000 calls
maps_reverse_geocode lat: number, lng: number 坐标 → 地址 $5 / 1000 calls
maps_search_places query: str, location?, radius? 按名称/类别搜索地点,靠近某个点 $17-32 / 1000 (text search) or less for nearby
maps_place_details place_id: str 用完整详情来充实一个地点 $17 / 1000 base + add-ons per field
maps_distance_matrix origins[], destinations[], mode?, departure_time? 多个点之间的批量距离/时间 $5 / 1000 elements (origin×destination)
maps_directions origin, destination, mode?, waypoints? 一条路线的转向导航 $5 / 1000 calls
maps_elevation locations: [{lat, lng}] 一条路径或多个点的高程信息 $5 / 1000 calls

成本与限制

运行它的成本

API 配额
按 API。默认项目有上限但可提高。
每次调用 Token 数
很小;成本是货币而不是 token
费用
按次付费。地理编码 $5/1k。地点详情 $17/1k。距离矩阵 $5/1k 元素。历史上有 $200/月的免费额度 — 验证当前 Google 政策。
提示
无限期缓存地理编码的地址(它们不会改变)。距离矩阵是一个提示词内花掉$50的简单方法 — 调用前始终计算出发地 × 目的地。

安全

权限、密钥、影响范围

凭据存储: API key 在环境变量 GOOGLE_MAPS_API_KEY 中。在 Google Cloud 控制台中按 API 限制 key(如果可能的话,按 IP/referrer)。
数据出站: 所有调用发往 maps.googleapis.com
切勿授予: 不受限制的全球可用 key — 可以从构建产物中被抓取并被滥用

故障排查

常见错误与修复

REQUEST_DENIED

API 没有为你的 key 启用,或者账单未配置。在 Cloud 控制台中启用每个 API(地理编码、地点、路线导航),设置账单。

OVER_QUERY_LIMIT

你达到了每秒或每天的上限。添加节流;如果需要,在 Cloud 控制台中提高配额。

ZERO_RESULTS on geocode

地址不明确或按写入的方式不存在。尝试添加国家/州,或改用地点自动完成。

Distance matrix INVALID_REQUEST

检查出发地×目的地是否超过每次调用的元素限制(因套餐而异)。分块请求。

替代方案

Google Maps 对比其他方案

替代方案何时用它替代权衡
OpenStreetMap (Nominatim) via fetch免费,无需 API key,愿意自己进行速率限制并接受较低的数据质量POI 数据稀疏;Nominatim 的使用政策限制了重度使用
Mapbox via custom MCP你想要一个管理型替代方案,高量时通常有更好的价格还没有官方 MCP
HERE / TomTom APIs via custom MCP在 Google 较弱的地区进行路由/POI没有官方 MCP

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills