使用说明
谷歌地图MCP服务器
提供对Google Maps API访问的模型上下文协议（MCP）服务器。该服务器使人工智能助手能够使用谷歌地图服务对地址进行地理编码、搜索地点、获取路线、计算距离、检索高程数据等。
特性
此MCP服务器提供以下工具：
🗺️ 岩芯测绘工具
maps_geocode-将地址转换为坐标maps_reverse_geocode-将坐标转换为地址maps_search_places-按查询搜索地点maps_place_details-获取有关地点的详细信息
🚗 导航和距离工具
maps_directions-获取各个位置之间的转弯方向maps_distance_matrix-计算多个起点/终点对的旅行时间/距离
🏔️ 地理数据工具
maps_elevation-获取位置的高程数据
安装
先决条件
- 谷歌地图API密钥：从获取API密钥 谷歌云控制台
- 启用所需的API：确保为您的项目启用了以下API：
- 地理编码API
- 地点API（新增）- 取代旧式Places API
- 路线API- 取代传统的方向API和距离矩阵API
- API高程
备注：此服务器使用官方 googlemaps Python包，可自动处理较新的API版本，并确保与谷歌最新服务的兼容性。这消除了遗留的API问题，并提供了强大的、面向未来的集成。
从GitHub安装
# Install using uvx (recommended)
uvx --from git+https://github.com/yourusername/google-maps-mcp-server google-maps-server
# Or install using pip
pip install git+https://github.com/yourusername/google-maps-mcp-server
地方发展
# Clone the repository
git clone https://github.com/yourusername/google-maps-mcp-server
cd google-maps-mcp-server
# Install dependencies
uv sync
# Set up environment variables
cp .env.example .env
# Edit .env and add your Google Maps API key
# Test the server
uv run python test_server.py
# Run the server
uv run python main.py
配置
环境变量
创建一个 .env 包含以下变量的文件：
# Required: Your Google Maps API Key
GOOGLE_MAPS_API_KEY=your_api_key_here
# Optional: Enable debug logging
DEBUG=true
MCP客户端配置
将此添加到您的MCP客户端配置中（例如，Claude Desktop）：
{
"mcpServers": {
"google-maps": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/yourusername/google-maps-mcp-server",
"google-maps-server"
],
"env": {
"GOOGLE_MAPS_API_KEY": "your_api_key_here"
}
}
}
}
使用示例
地理编码
# Convert address to coordinates
{
"tool": "maps_geocode",
"arguments": {
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
}
}
地点搜索
# Search for restaurants near a location
{
"tool": "maps_search_places",
"arguments": {
"query": "restaurants",
"location": {"latitude": 37.7749, "longitude": -122.4194},
"radius": 5000
}
}
方向
# Get driving directions
{
"tool": "maps_directions",
"arguments": {
"origin": "San Francisco, CA",
"destination": "Los Angeles, CA",
"mode": "driving"
}
}
距离矩阵
# Calculate distances between multiple points
{
"tool": "maps_distance_matrix",
"arguments": {
"origins": ["San Francisco, CA", "Oakland, CA"],
"destinations": ["Los Angeles, CA", "San Diego, CA"],
"mode": "driving"
}
}
api参考
地图_地理编码
将地址转换为地理坐标。
参数：
address（string，必填）：要进行地理编码的地址
退货： 位置坐标、格式化地址和地点ID
maps_reverse_geocode
将坐标转换为地址。
参数：
latitude（数字，必填）：纬度坐标（-90到90）longitude（数字，必填）：经度坐标（-180至180）
退货： 格式化地址、地点ID和地址组件
地图_搜索_地点
使用文本查询搜索地点。
参数：
query（字符串，必填）：搜索查询location（对象，可选）：带纬度/经度的中心点radius（数字，可选）：搜索半径（米）（最大50000）
退货： 包含名称、地址、坐标、评级和类型的地点数组
地图_地点_详细信息
获取特定地点的详细信息。
参数：
place_id（字符串，必填）：谷歌地点ID
退货： 详细的地点信息，包括联系方式、时间、评论
地图_方向
获取各个位置之间的转弯方向。
参数：
origin（字符串，必填）：起始位置destination（字符串，必填）：结束位置mode（字符串，可选）：旅行模式（驾驶、步行、骑自行车、公交）
退货： 路线信息，包括步骤、距离和持续时间
地图_距离_矩阵
计算多个起点/终点对的旅行距离和时间。
参数：
origins（array，必填）：原点位置数组destinations（array，必填）：目标位置数组mode（字符串，可选）：旅行模式（驾驶、步行、骑自行车、公交）
退货： 所有起点/终点组合的距离和持续时间矩阵
地图_立面图
获取位置的高程数据。
参数：
locations（array，必填）：具有纬度/经度的对象数组
退货： 每个位置的高程数据（单位：米）
发展
运行测试
# Run all test cases
uv run python test_server.py
# Run with verbose output
uv run python test_server.py --verbose
项目结构
google-maps-mcp-server/
├── google_maps_mcp_server/
│ ├── __init__.py
│ ├── __main__.py
│ ├── server.py # MCP server implementation
│ ├── handlers.py # Google Maps API handlers
│ └── tools.json # Tool schema definitions
├── test_cases.json # Test cases for all tools
├── test_server.py # Test runner
├── main.py # Server entry point
├── pyproject.toml # Project configuration
└── README.md
错误处理
该服务器包括全面的错误处理功能，用于：
- 缺少API密钥或密钥无效
- 坐标无效（超出范围）
- 缺少必要参数
- 谷歌地图API错误
- 网络连接问题
- 无效的旅行模式
- 请求格式错误
费率限制和配额
请注意Google Maps API配额和费率限制：
- 地理编码API：每月40000个请求（免费级别）
- 地点API：因请求类型而异
- 距离矩阵API：每月40000个元素
- API指南：每月40000次请求
- API高程：每月40000次请求
看 谷歌地图平台定价 对于当前的限制。
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 运行测试套件
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
