项目介绍
MCP Google 地图服务器
一个强大的模型上下文协议（MCP）服务器，提供全面的 Google 地图 API 集成，支持流式 HTTP 传输和大型语言模型处理能力。
🙌 特别感谢
本项目得到了社区的贡献。
特别感谢 @junyinnnn 帮助添加了对 streamablehttp 的支持。
✅ 测试状态
此 MCP 服务器已测试并验证可与以下内容正确工作：
- Claude 桌面版
- Dive 桌面版
- MCP 协议实现
所有工具和功能通过实际测试确认有效。
功能
🆕 最新更新
- ℹ️ 提醒：在使用新地点功能之前，请在 https://console.cloud.google.com 启用 Places API（新）。
🗺️ Google 地图集成
-
位置搜索
- 根据特定位置搜索附近的地点，自定义半径和过滤器
- 获取详细的位置信息，包括评分、营业时间及联系方式
-
地理编码服务
- 将地址转换为坐标（正向地理编码）
- 将坐标转换为地址（反向地理编码）
-
距离与方向
- 计算多个起点和终点之间的距离和旅行时间
- 获取两点之间的详细导航方向
- 支持不同的出行方式（驾车、步行、骑车、公共交通）
-
高程数据
- 获取特定位置的高程数据
🚀 高级功能
- 流式 HTTP 传输：最新 MCP 协议，具有实时流式传输能力
- 会话管理：基于 UUID 的有状态会话
- 多连接支持：处理多个并发客户端连接
- 回声服务：内置测试工具以检查 MCP 服务器功能
安装
⚠️ 重要通知：此服务器使用 HTTP 传输，而非 stdio。直接在 MCP 服务器设置中使用 npx 是不被支持的。
方法 1：全局安装（推荐）
# 全局安装
npm install -g @cablate/mcp-google-map
# 运行服务器
mcp-google-map --port 3000 --apikey "your_api_key_here"
# 使用短选项
mcp-google-map -p 3000 -k "your_api_key_here"
方法 2：使用 npx（快速启动）
⚠️ 警告：不能直接在 MCP 服务器设置中使用 stdio 模式
步骤 1：在终端中启动 HTTP 服务器
# 在单独的终端运行
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
# 或使用环境变量
GOOGLE_MAPS_API_KEY=YOUR_API_KEY npx @cablate/mcp-google-map
步骤 2：配置 MCP 客户端使用 HTTP
{
"mcp-google-map": {
"transport": "http",
"url": "http://localhost:3000/mcp"
}
}
❌ 应避免的常见错误
// 这将**不起作用** - 不支持 stdio 模式
{
"mcp-google-map": {
"command": "npx",
"args": ["@cablate/mcp-google-map"]
}
}
服务器信息
- 端点：
http://localhost:3000/mcp - 传输：HTTP（非 stdio）
- 工具：8 个 Google 地图工具可用
API 密钥配置
API 密钥可以通过三种方式提供（优先级顺序）：
-
HTTP 头部（最高优先级）
// MCP 客户端配置 { "mcp-google-map": { "transport": "streamableHttp", "url": "http://localhost:3000/mcp", // 如果您的 MCP 客户端支持 'headers' "headers": { "X-Google-Maps-API-Key": "YOUR_API_KEY" } } } -
命令行
mcp-google-map --apikey YOUR_API_KEY -
环境变量（.env 文件或命令行）
GOOGLE_MAPS_API_KEY=your_api_key_here MCP_SERVER_PORT=3000
可用工具
服务器提供了以下工具：
Google 地图工具
- search_nearby - 根据位置搜索附近的地点，可选地按关键词、距离、评分和营业时间进行筛选
- get_place_details - 获取特定地点的详细信息，包括联系方式、评论、评分和营业时间
- maps_geocode - 将地址或地点名称转换为地理坐标（纬度和经度）
- maps_reverse_geocode - 将地理坐标转换为人类可读的地址
- maps_distance_matrix - 计算多个起点和终点之间的旅行距离和时长
- maps_directions - 获取两个地点之间的详细导航方向
- maps_elevation - 获取特定地理位置的高度数据（海平面上的高度）
开发
本地开发
# 克隆仓库
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map
# 安装依赖
npm install
# 设置环境变量
cp .env.example .env
# 编辑 .env 文件以包含您的 API 密钥
# 构建项目
npm run build
# 启动服务器
npm start
# 或者在开发模式下运行
npm run dev
项目结构
src/
├── cli.ts # 主 CLI 入口点
├── config.ts # 服务器配置
├── index.ts # 包导出
├── core/
│ └── BaseMcpServer.ts # 基础 MCP 服务器，支持流式 HTTP
└── tools/
└── maps/ # Google 地图工具
├── toolclass.ts # Google 地图 API 客户端
├── searchPlaces.ts # 地图服务层
├── searchNearby.ts # 搜索附近地点
├── placeDetails.ts # 地点详情
├── geocode.ts # 地理编码
├── reverseGeocode.ts # 反向地理编码
├── distanceMatrix.ts # 距离矩阵
├── directions.ts # 方向
└── elevation.ts # 高程数据
技术栈
- TypeScript - 类型安全开发
- Node.js - 运行时环境
- Google Maps Services JS - Google 地图 API 集成
- Model Context Protocol SDK - MCP 协议实现
- Express.js - HTTP 服务器框架
- Zod - 模式验证
安全考虑
- API 密钥在服务器端处理以确保安全
- 生产环境中提供 DNS 重新绑定保护
- 使用 Zod 模式进行输入验证
- 错误处理和日志记录
许可证
MIT
贡献
欢迎社区参与和贡献！以下是您可以如何贡献的方法：
- ⭐️ 如果您觉得这个项目有用，请给它点赞
- 🐛 提交问题：报告错误或提出建议
- 🔧 创建拉取请求：提交代码改进
- 📖 文档：帮助改进文档
联系
如果您有任何问题或建议，请随时联系我们：
- 📧 邮件：reahtuoo310109@gmail.com
- 💻 GitHub：CabLate
- 🤝 合作：欢迎讨论项目合作
- 📚 技术指导：诚挚欢迎您的建议和指导
更新日志
v0.0.19（最新）
- 新的 Places API 集成：更新为使用 Google 新的 Places API（新），而不是旧的 API，以解决 HTTP 403 错误并确保持续的功能性。
v0.0.18
- 错误响应改进：现在所有错误消息均为英文，并且包含更多详细信息（以前是中文）
v0.0.17
- 增加了 HTTP 头认证：支持通过 MCP 客户端配置中的
X-Google-Maps-API-Key头传递 API 密钥 - 解决了并发用户问题：每个会话现在都使用自己的 API 密钥，没有冲突
- 解决了 npx 执行问题：解决了模块捆绑问题
- 改进了文档：更清晰的设置说明
v0.0.14
- 添加了流式 HTTP 传输支持
- 改进了 CLI 界面，带有表情符号指示符
- 增强了错误处理和日志记录
- 添加了详细的工具描述，用于 LLM 集成
- 更新到最新的 MCP SDK 版本