MCP 服务器

Google Maps MCP Server

Enables interaction with Google Maps API for geocoding, place search, directions, distance matrices, and elevation data through natural language.

README

Google Maps MCP Server

基于 FastMCP 框架的 Google Maps MCP 服务器，提供完整的 Google Maps API 功能。

功能特性

🗺️ 地理编码: 地址与坐标相互转换
🔍 地点搜索: 使用 Google Places API 搜索地点
📍 地点详情: 获取详细的地点信息
📏 距离计算: 多点间距离和时间矩阵
⛰️ 海拔数据: 获取位置海拔信息
🧭 路线规划: 多种交通方式的路线指导

安装和使用

方式 1：直接使用 uvx（推荐）

无需安装，直接运行：

# 安装 uv（如果未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 直接运行（会自动下载）
uvx --from mclabs.google_maps_mcp_server google-maps-mcp

方式 2：安装到系统

# 使用 pip
pip install mclabs.google_maps_mcp_server

# 使用 uv
uv add mclabs.google_maps_mcp_server

# 运行
google-maps-mcp

方式 3：从源码运行（开发）

# 克隆项目
git clone https://github.com/lesonky/google-maps-mcp.git
cd google-maps-mcp

# 安装 uv（如果未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步项目依赖（自动创建虚拟环境）
uv sync

# 运行
uv run google-maps-mcp

配置

1. 获取 Google Maps API Key

访问 Google Cloud Console
创建新项目或选择现有项目
启用以下 API：
- Maps JavaScript API
- Geocoding API
- Places API
- Distance Matrix API
- Elevation API
- Directions API
创建 API 密钥并记录

2. 设置环境变量

export GOOGLE_MAPS_API_KEY="your_api_key_here"

或创建 .env 文件：

echo "GOOGLE_MAPS_API_KEY=your_api_key_here" > .env

运行服务器

使用 uv 运行（推荐）

# 方式1：使用脚本入口点
uv run google-maps-mcp

# 方式2：直接运行 Python 文件
uv run python google_maps_server.py

# 方式3：使用启动脚本
./start_server.sh

不同传输方式

默认使用 STDIO 传输，你也可以使用 HTTP 传输：

# STDIO 传输（默认）
uv run google-maps-mcp

# HTTP 传输
MCP_TRANSPORT=streamable-http MCP_PORT=8000 uv run google-maps-mcp

MCP 工具使用示例

地理编码

# 将地址转换为坐标
await maps_geocode("北京市天安门广场")

反向地理编码

# 将坐标转换为地址
await maps_reverse_geocode(39.9042, 116.4074)

搜索地点

# 搜索餐厅
await maps_search_places("北京餐厅", location={"latitude": 39.9042, "longitude": 116.4074}, radius=5000)

获取地点详情

# 获取详细信息
await maps_place_details("ChIJD3uTd9hfUDERCA0j7L2EMqo")

距离矩阵

# 计算多点间距离
await maps_distance_matrix(
    origins=["北京", "上海"],
    destinations=["广州", "深圳"],
    mode="driving"
)

海拔数据

# 获取海拔
await maps_elevation([
    {"latitude": 39.9042, "longitude": 116.4074},
    {"latitude": 31.2304, "longitude": 121.4737}
])

路线规划

# 获取导航路线
await maps_directions("北京", "上海", mode="driving")

与 Claude Desktop 集成

打开 Claude Desktop 配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
选择以下配置方式之一：

方式 1：使用 uvx（推荐）

从 PyPI 直接运行，无需本地安装：

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": ["--from", "mclabs.google_maps_mcp_server", "google-maps-mcp"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key_here"
      }
    }
  }
}

方式 2：使用已安装的包

如果已通过 pip install mclabs.google_maps_mcp_server 安装：

{
  "mcpServers": {
    "google-maps": {
      "command": "google-maps-mcp",
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key_here"
      }
    }
  }
}

方式 3：从本地开发目录运行

如果从源码运行：

{
  "mcpServers": {
    "google-maps": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/google-maps-mcp", "google-maps-mcp"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key_here"
      }
    }
  }
}

重启 Claude Desktop

配置说明

uvx 方式：自动下载并运行最新版本，无需手动安装或更新
已安装包方式：使用系统已安装的包，启动速度快
本地开发方式：适合开发和测试，可以修改源码

开发

项目结构

google-maps-mcp/
├── google_maps_server.py  # 主服务器文件
├── pyproject.toml         # 项目配置
├── README.md              # 本文档
└── .env                   # 环境变量（需要创建）

代码特性

✅ 类型注解完整
✅ 异步操作支持
✅ 错误处理和日志记录
✅ Pydantic 数据模型验证
✅ Context 对象支持 MCP 功能

开发工作流

# 安装开发依赖
make install

# 代码格式化和检查
make format             # 格式化代码
make lint               # 代码检查

# 运行测试
uv run python test_server.py

# 构建和发布
make build              # 构建包
make check              # 检查包
make test-publish       # 发布到 TestPyPI
make publish            # 发布到 PyPI

发布到 PyPI

本项目支持多种发布方式：

使用 twine（推荐）：

make publish            # 使用 twine 发布
./publish_twine.sh      # 或使用发布脚本

使用 uv：

make publish-uv         # 使用 uv 发布

详细发布说明请参考 PUBLISHING.md。

🚀 快速开始

获取 Google Maps API 密钥：访问 Google Cloud Console 创建 API 密钥

设置环境变量：

export GOOGLE_MAPS_API_KEY="your_api_key_here"

配置 Claude Desktop：

将以下配置添加到 Claude Desktop 配置文件：

{
  "mcpServers": {
    "google-maps": {
      "command": "uvx",
      "args": ["--from", "mclabs.google_maps_mcp_server", "google-maps-mcp"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key_here"
      }
    }
  }
}