Geocode MCP Server

地理码MCP服务器

模型上下文协议（MCP）服务器，使用OpenStreetMap Nomatim API为城市和地点提供纬度/经度坐标。

特性

• 🌍 全球地理编码：获取全球任何位置的坐标
• 🆓 免费API：使用OpenStreetMap Nomatim（不需要API密钥）
• � MCP集成：适用于Cursor、VS Code、Claude Desktop和其他MCP兼容工具
• 📦 简易安装：通过PyPI安装 uvx geocode-mcp
• �️ 现代工具：使用Python 3.12+、async/await和全面测试构建

快速开始

安装

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

uvx geocode-mcp

或者用pip安装：

pip install geocode-mcp

MCP配置

添加到MCP客户端配置中：

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

请参阅 config/ 不同工具的具体示例目录。

可用工具

mcp_geocoding_get_coordinates

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

参数：

• location （必填）：城市名称、地址或位置（例如，“纽约”、“法国巴黎”、“西雅图主街123号”）
• limit （可选）：返回的最大结果数（默认值：1，最大值：10）

示例用法：

Get coordinates for Tokyo, Japan
Find the latitude and longitude of London, UK  
What are the coordinates for New York City?
Get coordinates for "1600 Pennsylvania Avenue, Washington DC" with limit 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
      }
    }
  ]
}

集成指南

光标

从以下位置复制配置 config/cursor-mcp.json 到您的光标MCP设置。

VS代码

从以下位置复制配置 config/vscode-mcp.json 您的VS代码MCP设置。

克劳德桌面

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

请参阅 配置README 有关详细的设置说明。

发展

设置

# Clone the repository
git clone https://github.com/X-McKay/geocode-mcp.git
cd geocode-mcp

# Install with development dependencies
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/geocode_mcp --cov-report=html

# Run specific test files
pytest tests/test_geocoding.py -v
pytest tests/test_mcp_server.py -v

代码质量

# Format code
ruff format

# Lint code
ruff check

# Run all checks
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/       # Main source code
│   └── server.py          # MCP server implementation
├── tests/                 # Test suite
│   ├── test_geocoding.py  # Geocoding functionality tests
│   ├── test_mcp_server.py # MCP server integration tests
│   ├── test_mcp.py        # MCP protocol tests
│   └── test_vscode.py     # VS Code integration tests
├── config/                # Configuration examples
│   ├── cursor-mcp.json    # Cursor configuration
│   ├── vscode-mcp.json    # VS Code configuration
│   ├── claude-desktop.json # Claude Desktop configuration
│   └── README.md          # Configuration guide
├── docs/                  # Documentation
├── pyproject.toml         # Project configuration
├── requirements.txt       # Production dependencies
├── requirements-dev.txt   # Development dependencies
└── README.md             # This file

api参考

核心功能

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]:
    """
    Geocode a location using OpenStreetMap Nominatim API.
    
    Args:
        location: The location to geocode
        limit: Maximum number of results (1-10)
        
    Returns:
        Dictionary containing query, results_count, and coordinates
    """

MCP服务器

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

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试(pytest)
5. 跑linting(ruff check && ruff format)
6. 提交您的更改(git commit -m 'Add amazing feature')
7. 推到分支(git push origin feature/amazing-feature)
8. 打开拉取请求

看 贡献.md 了解更多详情。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 开放街道图 提供免费的Nominim地理编码服务
• 模型上下文协议 对于协议规范
• Python MCP SDK团队提供卓越的工具

制作棉绒

格式代码

制作格式

类型检查

进行类型检查

运行所有检查

检查全部

### Testing

Run all tests

make test

Run with coverage

make test-cov

Run specific test categories

pytest tests/test_geocoding.py -v # Geocoding tests pytest tests/test_mcp.py -v # MCP server tests python tests/test_mcp_server.py # Integration tests python tests/test_vscode.py # VSCode tests

### 安装

Install production dependencies

make install

Install development dependencies

make install-dev

## 配置

### 光标集成

看 [光标集成指南](docs/cursor-integration.md) 有关详细的设置说明。

### VSCode集成

运行VSCode集成测试：

python tests/test_vscode.py

## api参考

### 地理编码功能

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]: """Geocode a location using Nominatim API."""

### MCP服务器

服务器提供 `get_coordinates` 可以通过MCP协议调用的工具。

## 贡献

1. 分叉存储库
1. 创建要素分支
1. 进行更改
1. 运行测试： `make test`
1. 运行linting： `make lint`
1. 提交拉取请求

看 [贡献.md](CONTRIBUTING.md) 了解更多详情。

## 许可证

此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。

## 致谢

- [开放街道图](https://www.openstreetmap.org/) 用于提供Nominim地理编码服务
- [主控程序](https://modelcontextprotocol.io/) 对于协议规范

🚀 Quick Setup Instructions

1. Create Project Folder:

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

1. 复制文件：

将上面的每个文件部分复制到具有相应名称的文件中

1. 安装依赖关系：

   pip install -r requirements.txt

1. 运行服务器：

   python geocoding_server.py

1. 配置MCP客户端：

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

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