地理编码-MCP

Name: 地理编码-MCP
Author: X-McKay

作者：X-McKay2 星标更新：2025-07-02

安装使用来源：spider==github.com

项目介绍

Geocode MCP Server

一个使用OpenStreetMap Nominatim API提供城市和地点经纬度坐标的Model Context Protocol (MCP)服务器。

特性

🌍 全球地理编码：获取世界各地任何位置的坐标
🆓 免费API：使用OpenStreetMap Nominatim（无需API密钥）
� MCP集成：与Cursor、VS Code、Claude Desktop和其他兼容MCP的工具一起工作
📦 简单安装：通过PyPI使用uvx geocode-mcp进行安装
�️ 现代工具：使用Python 3.12+、异步/等待和全面测试构建

快速开始

安装

从PyPI使用uvx（推荐）安装包：

uvx geocode-mcp

或者使用pip安装：

pip install geocode-mcp

MCP配置

添加到您的MCP客户端配置中：

{
  "mcpServers": {
    "geocoding": {
      "command": "uvx",
      "args": ["geocode-mcp"]
    }
  }
}

查看config/目录以获取不同工具的具体示例。

可用工具

`mcp_geocoding_get_coordinates`

获取城市或地点的经纬度坐标。

参数：

location（必需）：城市名称、地址或位置（例如："New York"，"Paris, France"，"123 Main St, Seattle"）
limit（可选）：返回结果的最大数量（默认值：1，最大值：10）

示例用法：

获取东京，日本的坐标
查找伦敦，英国的纬度和经度
纽约市的坐标是什么？
获取“1600 Pennsylvania Avenue, Washington DC”的坐标，限制为5

响应格式：

{
  "query": "Tokyo, Japan",
  "results_count": 1,
  "coordinates": [
    {
      "latitude": 35.6762,
      "longitude": 139.6503,
      "display_name": "Tokyo, Japan",
      "place_id": "282885117",
      "type": "city",
      "class": "place",
      "importance": 0.9,
      "bounding_box": {
        "south": 35.619,
        "north": 35.739,
        "west": 139.619,
        "east": 139.682
      }
    }
  ]
}

集成指南

Cursor

将配置从config/cursor-mcp.json复制到您的Cursor MCP设置中。

VS Code

将配置从config/vscode-mcp.json复制到您的VS Code MCP设置中。

Claude Desktop

将配置从config/claude-desktop.json复制到您的Claude Desktop配置文件中。

查看config README以获取详细的设置说明。

开发

设置

# 克隆仓库
git clone https://github.com/X-McKay/geocode-mcp.git
cd geocode-mcp

# 使用开发依赖项安装
pip install -e ".[dev]"

运行测试

# 运行所有测试
pytest

# 带覆盖率运行
pytest --cov=src/geocode_mcp --cov-report=html

# 运行特定测试文件
pytest tests/test_geocoding.py -v
pytest tests/test_mcp_server.py -v

代码质量

# 格式化代码
ruff format

# 检查代码
ruff check

# 运行所有检查
ruff check && ruff format --check

本地开发

对于本地开发和测试，您可以直接运行服务器：

python -m geocode_mcp.server

或者在您的MCP客户端中使用开发配置：

{
  "mcpServers": {
    "geocoding": {
      "command": "python",
      "args": ["-m", "geocode_mcp.server"],
      "cwd": "/path/to/geocode-mcp",
      "env": {
        "PYTHONPATH": "/path/to/geocode-mcp/src"
      }
    }
  }
}

项目结构

geocode-mcp/
├── src/geocode_mcp/       # 主源代码
│   └── server.py          # MCP服务器实现
├── tests/                 # 测试套件
│   ├── test_geocoding.py  # 地理编码功能测试
│   ├── test_mcp_server.py # MCP服务器集成测试
│   ├── test_mcp.py        # MCP协议测试
│   └── test_vscode.py     # VS Code集成测试
├── config/                # 配置示例
│   ├── cursor-mcp.json    # Cursor配置
│   ├── vscode-mcp.json    # VS Code配置
│   ├── claude-desktop.json # Claude Desktop配置
│   └── README.md          # 配置指南
├── docs/                  # 文档
├── pyproject.toml         # 项目配置
├── requirements.txt       # 生产依赖项
├── requirements-dev.txt   # 开发依赖项
└── README.md             # 本文件

API参考

核心函数

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]:
    """
    使用OpenStreetMap Nominatim API对位置进行地理编码。
    
    参数：
        location: 要地理编码的位置
        limit: 结果的最大数量（1-10）
        
    返回：
        包含查询、结果计数和坐标的字典
    """

MCP服务器

该服务器实现了模型上下文协议，并提供了mcp_geocoding_get_coordinates工具，用于在兼容MCP的应用程序中使用。

贡献

分叉仓库
创建特性分支（git checkout -b feature/amazing-feature）
进行更改
运行测试（pytest）
运行代码检查（ruff check && ruff format）
提交更改（git commit -m 'Add amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开拉取请求

查看CONTRIBUTING.md以获取更多详细信息。

许可证

该项目根据MIT许可证授权 - 查看LICENSE文件以获取详细信息。

致谢

OpenStreetMap 提供免费的Nominatim地理编码服务
Model Context Protocol 提供协议规范
Python MCP SDK团队提供的优秀工具

🚀 快速设置说明

创建项目文件夹：

mkdir mcp-geocoding-server-python
cd mcp-geocoding-server-python

复制文件： 将上述每个文件部分复制到相应命名的文件中
安装依赖项：
```
pip install -r requirements.txt
```
运行服务器：
```
python geocoding_server.py
```

配置MCP客户端： 添加到您的MCP客户端（如Claude Desktop）配置中：

{
  "mcpServers": {
    "geocoding": {
      "command": "python",
      "args": ["/full/path/to/mcp-geocoding-server-python/geocoding_server.py"]
    }
  }
}