使用说明
chuk-mcp地理编码器
通过Nominim/OpenStreetMap进行地理编码和位置发现MCP服务器。
提供正向/反向地理编码、边界框提取、附近地点发现、批量地理编码、路线航路点和管理边界查找，旨在与其他MCP地理空间服务器（DEM、STAC等）协同工作。
这是一个为学习和测试目的而提供的演示项目。
工具
| 工具 | 说明 |
|---|---|
geocode |
地名坐标（lat、lon、bbox、地址） |
reverse_geocode |
地名和地址坐标 |
bbox_from_place |
地点名称 [west, south, east, north] 用于DEM/STAC工具的bbox |
nearby_places |
在多个尺度上查找坐标附近的位置 |
admin_boundaries |
行政层级（国家、州、县、市、郊区） |
batch_geocode |
在一次通话中对多个地名进行地理编码 |
route_waypoints |
按顺序对航路点进行地理编码并计算路线距离 |
distance_matrix |
计算多个点之间的距离矩阵 |
geocoder_status |
服务器状态和缓存统计信息 |
geocoder_capabilities |
LLM指导下的完整功能列表 |
安装
使用uvx（推荐-无需安装！）
使用服务器的最简单方法是 uvx，无需安装即可运行：
uvx chuk-mcp-geocoder
这将自动下载并运行最新版本。非常适合克劳德桌面！
使用紫外线（建议用于开发）
# Install from PyPI
uv pip install chuk-mcp-geocoder
# Or clone and install from source
git clone <repository-url>
cd chuk-mcp-geocoder
uv sync --dev
使用pip（传统）
pip install chuk-mcp-geocoder
用法
使用克劳德桌面
选项1：使用公共服务器（最简单）
连接到托管的公共服务器 geocoder.chukai.io:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"geocoder": {
"url": "https://geocoder.chukai.io/mcp"
}
}
}
选项2：流式HTTP URL（本地）
在本地运行服务器并通过HTTP连接：
{
"mcpServers": {
"geocoder": {
"url": "http://localhost:8010/mcp"
}
}
}
然后启动服务器：
uvx chuk-mcp-geocoder http
选项3：使用uvx在本地运行
{
"mcpServers": {
"geocoder": {
"command": "uvx",
"args": ["chuk-mcp-geocoder"]
}
}
}
选项4：使用pip在本地运行
{
"mcpServers": {
"geocoder": {
"command": "chuk-mcp-geocoder"
}
}
}
独立
直接运行服务器：
# With uvx (recommended - always latest version)
uvx chuk-mcp-geocoder
# With uvx in HTTP mode
uvx chuk-mcp-geocoder http
# Or if installed locally
chuk-mcp-geocoder
chuk-mcp-geocoder http
或者使用uv/Python：
# STDIO mode (default, for MCP clients)
uv run chuk-mcp-geocoder
# or: python -m chuk_mcp_geocoder.server
# HTTP mode (for web access and streamable HTTP)
uv run chuk-mcp-geocoder http
# or: python -m chuk_mcp_geocoder.server http
# HTTP mode with custom host/port
uv run chuk-mcp-geocoder http --host 0.0.0.0 --port 9000
STDIO模式 适用于Claude Desktop和MCP-cli等MCP客户端。 HTTP模式 在上运行web服务器http://localhost:8010用于基于HTTP的MCP客户端。
使用MCP CLI
uv run mcp-cli --server geocoder,dem,stac
然后问：
“获取Mersea岛的高程剖面图”
LLM将使用 bbox_from_place 或 geocode 然后将坐标传递给DEM服务器。
配置
| 环境变量 | 描述 | 默认值 |
|---|---|---|
NOMINATIM_EMAIL |
Nomatim API的联系电子邮件 | （无） |
NOMINATIM_BASE_URL |
自定义提名实例URL | https://nominatim.openstreetmap.org |
MCP_STDIO |
强制stdio传输模式 | （自动检测） |
发展
设置
# Clone the repository
git clone <repository-url>
cd chuk-mcp-geocoder
# Install with uv (recommended)
uv sync --dev
# Or with pip
pip install -e ".[dev]"
运行测试
make test # Run tests
make test-cov # Run tests with coverage
make coverage-report # Show coverage report
代码质量
make lint # Run linters
make format # Auto-format code
make typecheck # Run type checking
make security # Run security checks
make check # Run all checks
建筑
make build # Build package
make publish-test # Upload to TestPyPI for testing
make publish-manual # Manually upload to PyPI (requires PYPI_TOKEN)
make publish # Create tag and trigger GitHub Actions release
建筑
遵循与chuk-mcp-dem相同的5层模式：
- core/nominatim.py --具有速率限制和LRU缓存的异步HTTP客户端
- core/geocer.py --具有验证和类型化数据类结果的异步管理器
- 模型/响应.py --Pydantic v2响应模型(
extra="forbid",to_text()) - 警察py --所有配置、消息和元数据
- 工具/*/api.py --MCP工具注册
@mcp.tool()装饰器
公用服务器
公共实例托管在 geocer.chukai.io 为了便于访问：
- 统一资源定位符:
https://geocoder.chukai.io/mcp - 协议：HTTPS上的MCP（流式HTTP）
- 免费使用：不需要API密钥
- 始终保持最新状态：运行最新版本
只需将其添加到您的Claude Desktop配置中：
{
"mcpServers": {
"geocoder": {
"url": "https://geocoder.chukai.io/mcp"
}
}
}
数据源
- 数据许可证： ODbL 1.0 版本
- API速率限制：1请求/秒（公共API）
- 结果缓存在内存中（1小时TTL）
许可证
阿帕奇-2.0
