地理码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-mcpMCP配置
添加到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 fileapi参考
核心功能
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兼容应用程序的工具。
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试(
pytest) - 跑linting(
ruff check && ruff format) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
看 贡献.md 了解更多详情。
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
制作棉绒
格式代码
制作格式
类型检查
进行类型检查
运行所有检查
检查全部
### 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
- Create Project Folder:
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"]
}
}
}```