MCP Google Map Server

Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.

English | 繁體中文

• 18工具 --14原子+4复合（探索区域、规划路线、比较地点、本地排名跟踪器）
• 3种模式 --stdio、StreamableHTTP、独立的exec-CLI
• 代理技能 --内置技能定义教人工智能如何链接地理工具(skills/google-maps/)

vs谷歌停飞精简版

快速开始

# stdio (Claude Desktop, Cursor, etc.)
npx @cablate/mcp-google-map --stdio

# exec CLI — no server needed
npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'

# HTTP server
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

特别感谢

特别感谢 @junyinnnn 用于帮助添加支持 streamablehttp.

可用工具

所有工具都带有注释 readOnlyHint: true 和 destructiveHint: false --MCP客户端可以自动批准这些，无需用户确认。

先决条件：启用 地点API（新增） 和 路线API 在 谷歌云控制台 在使用位置相关和布线工具之前。

安装

方法1:stdio（建议大多数客户端使用）

适用于Claude Desktop、Cursor、VS Code和任何支持stdio的MCP客户端：

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

减少上下文使用 --如果您只需要一部分工具，请设置 GOOGLE_MAPS_ENABLED_TOOLS 限制注册的工具：

{
  "env": {
    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
  }
}

省略或设置为 * 适用于所有18个工具（默认）。

方法2:HTTP服务器

对于多会话部署，per-request API密钥隔离或远程访问：

npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

# Bind to all interfaces for remote access (e.g. Docker, LAN)
npx @cablate/mcp-google-map --host 0.0.0.0 --port 3000 --apikey "YOUR_API_KEY"

然后配置您的MCP客户端：

{
  "mcpServers": {
    "google-maps": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

服务器信息

• 运输标准（ stdio）--stdio)或流式HTTP（默认）
• 工具：18个谷歌地图工具（14个原子+4个复合）——可通过以下方式过滤 GOOGLE_MAPS_ENABLED_TOOLS

CLI执行模式（代理技能）

无需运行MCP服务器即可直接使用工具：

npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'

所有18个可用工具： geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather, air-quality, static-map, batch-geocode-tool, search-along-route, explore-area, plan-route, compare-places, local-rank-tracker。参见 skills/google-maps/ 用于代理技能定义和全参数文档。

批处理地理代码

从文件中对数百个地址进行地理编码：

npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -

输入：每行一个地址。输出：JSON { total, succeeded, failed, results[] }默认并发：20个并行请求。

API密钥配置

API密钥可以通过三种方式（优先级顺序）提供：

1. HTTP 头 （最高优先级）

   {
     "mcp-google-map": {
       "transport": "streamableHttp",
       "url": "http://localhost:3000/mcp",
       "headers": {
         "X-Google-Maps-API-Key": "YOUR_API_KEY"
       }
     }
   }

1. 命令行

   mcp-google-map --apikey YOUR_API_KEY

1. 环境变量 （.env文件或命令行）

   GOOGLE_MAPS_API_KEY=your_api_key_here
   MCP_SERVER_PORT=3000
   MCP_SERVER_HOST=0.0.0.0

发展

本地开发

# Clone the repository
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API key

# Build the project
npm run build

# Start the server
npm start

# Or run in development mode
npm run dev

测试

# Run smoke tests (no API key required for basic tests)
npm test

# Run full E2E tests (requires GOOGLE_MAPS_API_KEY)
npm run test:e2e

项目结构

src/
├── cli.ts                        # CLI entry point
├── config.ts                     # Tool registration and server config
├── index.ts                      # Package exports
├── core/
│   └── BaseMcpServer.ts          # MCP server with streamable HTTP transport
├── services/
│   ├── NewPlacesService.ts       # Google Places API (New) client
│   ├── PlacesSearcher.ts         # Service facade layer
│   ├── RoutesService.ts          # Google Routes API client (directions, distance matrix, waypoint optimization)
│   └── toolclass.ts              # Google Maps API client (geocoding, timezone, elevation, static map)
├── tools/
│   └── maps/
│       ├── searchNearby.ts       # maps_search_nearby tool
│       ├── searchPlaces.ts       # maps_search_places tool
│       ├── placeDetails.ts       # maps_place_details tool
│       ├── geocode.ts            # maps_geocode tool
│       ├── reverseGeocode.ts     # maps_reverse_geocode tool
│       ├── distanceMatrix.ts     # maps_distance_matrix tool
│       ├── directions.ts         # maps_directions tool
│       ├── elevation.ts          # maps_elevation tool
│       ├── timezone.ts           # maps_timezone tool
│       ├── weather.ts            # maps_weather tool
│       ├── airQuality.ts         # maps_air_quality tool
│       ├── staticMap.ts          # maps_static_map tool
│       ├── batchGeocode.ts       # maps_batch_geocode tool
│       ├── searchAlongRoute.ts   # maps_search_along_route tool
│       ├── exploreArea.ts        # maps_explore_area (composite)
│       ├── planRoute.ts          # maps_plan_route (composite)
│       ├── comparePlaces.ts      # maps_compare_places (composite)
│       └── localRankTracker.ts   # maps_local_rank_tracker (composite)
└── utils/
    ├── apiKeyManager.ts          # API key management
    └── requestContext.ts         # Per-request context (API key isolation)
tests/
└── smoke.test.ts                 # Smoke + E2E test suite
skills/
├── google-maps/                  # Agent Skill — how to USE the tools
│   ├── SKILL.md                  # Tool map, recipes, invocation
│   └── references/
│       ├── tools-api.md          # Tool parameters + scenario recipes
│       ├── travel-planning.md    # Travel planning methodology
│       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis
└── project-docs/                 # Project Skill — how to DEVELOP/MAINTAIN
    ├── SKILL.md                  # Architecture overview + onboarding
    └── references/
        ├── architecture.md       # System design, code map, 9-file checklist
        ├── google-maps-api-guide.md  # API endpoints, pricing, gotchas
        ├── geo-domain-knowledge.md   # GIS fundamentals, Japan context
        └── decisions.md          # 10 ADRs (design decisions + rationale)

技术栈

• TypeScript -类型安全开发
• Node.js -运行时环境
• @谷歌地图/地点 -Google Places API（新增），用于位置搜索和详细信息
• 谷歌路线API -通过REST优化方向、距离矩阵和航路点
• @googlemaps/googlemaps服务js -地理编码、时区、海拔
• @模型上下文协议/sdk -MCP协议实现（v1.27+）
• Express.js -HTTP服务器框架
• 黄道带 -架构验证

安全

• API密钥在服务器端处理
• 用于多对映部署的逐会话API密钥隔离
• DNS重新绑定保护可用于生产
• 使用Zod模式进行输入验证

有关企业安全审查，请参阅 安全评估澄清 --涵盖许可、数据保护、凭证管理、工具污染和AI代理执行环境验证的23项清单。

要报告漏洞，请参阅 安全.md.

路线图

最近添加的内容

计划的

我们正在构建的用例

以下是推动我们做出工具决策的现实场景：

• 旅行计划 --“计划东京一日游”（地理编码→ 搜索→ 方向→ 天气）
• 房地产分析 --“分析这个社区：学校、通勤、洪水风险”（搜索附近×N+海拔+距离矩阵）
• 物流优化 --“从仓库高效地运送这12批货物”（计划路线）
• 外勤销售 --“拜访芝加哥的6位客户，尽量减少开车时间，找到午餐地点”（计划路线+在附近搜索）
• 灾害应对 --“最近的开放式医院？我在洪水区吗？”（搜索附近+海拔高度）
• 内容创作 --“奥斯汀餐厅密度和机场距离排名前五的街区”（探索面积+距离矩阵）
• 无障碍 --“轮椅无障碍餐厅，避开陡峭路线”（搜索附近+地点详情+海拔高度）
• 本地SEO --“审核我的餐厅在1公里内与竞争对手的排名”（搜索地点+比较地点+探索区域）

更新日志

看 更改日志.md 版本历史。

许可证

麻省理工学院

贡献

欢迎社区参与和贡献！请阅读 贡献.md 用于开发设置、编码指南和拉取请求过程。

• 提交问题：报告错误或提供建议
• 创建拉取请求：提交代码改进
• 文档：帮助改进文档

联系

• 电子邮件： reahtuoo310109@gmail.com
• github： 出租车

明星历史