google-maps-mcp

lesonky/google-maps-mcp

3.1

If you are the rightful owner of google-maps-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Google Maps MCP Server is a comprehensive server based on the FastMCP framework, offering full Google Maps API functionality.

Tools
7
Resources
0
Prompts
0

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

  1. 访问 Google Cloud Console
  2. 创建新项目或选择现有项目
  3. 启用以下 API：
    • Maps JavaScript API
    • Geocoding API
    • Places API
    • Distance Matrix API
    • Elevation API
    • Directions API
  4. 创建 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 集成

  1. 打开 Claude Desktop 配置文件：

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. 选择以下配置方式之一：

方式 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"
      }
    }
  }
}
  1. 重启 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 发布

详细发布说明请参考 。

🚀 快速开始

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

  2. 设置环境变量：

    export GOOGLE_MAPS_API_KEY="your_api_key_here"

  3. 配置 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"
      }
    }
  }
}

  4. 重启 Claude Desktop 即可使用！

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

相关链接