Geoapify MCP Server (Ori Shmila)

Geoapify MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供对Geoapify全套基于位置的API的访问。此服务器可将地理编码、路由、地点搜索和地理空间服务无缝集成到您的MCP兼容应用程序中。

🌟 特性

此服务器提供 14个强大的工具 涵盖所有主要位置服务：

📍 地理编码和地址服务

• forward_geocoding -用简化的结构将地址转换为坐标
• reverse_geocoding -将坐标转换为详细的GeoJSON地址信息
• suggest_places -实时地址建议和完成，如GeoJSON

🏢 地点和兴趣点

• places_search -使用GeoJSON输出和分页按类别搜索POI
• place_details -使用原始几何图形获取详细的位置信息

🗺️ 行政边界

• boundaries_part_of -以GeoJSON格式查找父级管理边界
• boundaries_consists_of -使用GeoJSON分页获取子边界

🚗 路线和导航

• get_route -使用逐步导航和旅行指标计算路线
• get_travel_times -生成起点和终点之间的距离/时间矩阵
• generate_isoline -创建可达性多边形（等时线/等距）
• combine_geometries -执行几何运算（并线/交点）

📮 邮政服务

• postcode_search -使用点/多边形几何体选项搜索邮政编码
• postcode_list -列出带有空间过滤器和分页的邮政编码

🌐 附加服务

• ip_to_location -将IP地址解析为全面的位置元数据

🚀 快速开始

先决条件

• Python 3.11或更高版本
• 紫外线 包管理器
• A. Geoapify API密钥 （免费版可用）

安装

1. 克隆和设置：

git clone 
cd geoapify-mcp-server
uv sync

1. 配置环境：

cp .env.example .env
# Edit .env and add your Geoapify API key:
# GEOAPIFY_KEY=your_actual_api_key_here

1. 测试安装：

uv run python test_server.py

获取API密钥

1. 访问 Geoapify.com
2. 注册一个免费帐户（无需信用卡）
3. 从仪表板生成API密钥
4. 免费套餐包括3000个请求/天

🔧 配置

MCP客户端设置

克劳德桌面

将此添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "geoapify": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/geoapify-mcp-server.git",
        "geoapify-server"
      ],
      "env": {
        "GEOAPIFY_KEY": "your_api_key_here"
      }
    }
  }
}

地方发展

{
  "mcpServers": {
    "geoapify": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/geoapify-mcp-server",
        "run",
        "geoapify-server"
      ],
      "env": {
        "GEOAPIFY_KEY": "your_api_key_here"
      }
    }
  }
}

📖 使用示例

地理编码示例

将地址转换为坐标：

{
  "tool": "forward_geocoding",
  "arguments": {
    "text": "Eiffel Tower, Paris",
    "language": "en"
  }
}

将坐标转换为地址（返回GeoJSON）：

{
  "tool": "reverse_geocoding",
  "arguments": {
    "lat": 48.8584,
    "lon": 2.2945,
    "language": "en"
  }
}

获取地址建议（返回GeoJSON）：

{
  "tool": "suggest_places",
  "arguments": {
    "text": "Times Sq",
    "language": "en"
  }
}

地点和POI示例

搜索餐馆（返回GeoJSON）：

{
  "tool": "places_search",
  "arguments": {
    "categories": "catering.restaurant",
    "filter": "circle:-73.986923,40.758896,500",
    "language": "en",
    "page": 1
  }
}

获取地点详细信息（返回单个GeoJSON功能）：

{
  "tool": "place_details",
  "arguments": {
    "lat": 48.8584,
    "lon": 2.2945,
    "language": "en"
  }
}

路由示例

使用逐步导航计算路线：

{
  "tool": "get_route",
  "arguments": {
    "waypoints": ["48.8584,2.2945", "48.8566,2.3522"],
    "mode": "driving"
  }
}

生成等时线（可达性多边形）：

{
  "tool": "generate_isoline",
  "arguments": {
    "lat": 48.8584,
    "lon": 2.2945,
    "type": "time",
    "mode": "walk",
    "range": 600
  }
}

行程时间矩阵：

{
  "tool": "get_travel_times",
  "arguments": {
    "origins": ["48.8584,2.2945", "48.8566,2.3522"],
    "destinations": ["48.8606,2.3376", "48.8629,2.3499"],
    "mode": "driving"
  }
}

组合几何图形：

{
  "tool": "combine_geometries",
  "arguments": {
    "operation": "union",
    "id": ["shape_id_1", "shape_id_2"]
  }
}

🛠️ api参考

核心参数

大多数工具支持以下常见参数：

• language -语言代码（ISO 639-1，例如“en”、“fr”、“de”）
• page -分页页码（默认值：1，每页20个结果）
• filter -使用Geoapify DSL的空间滤波器
• bias -结果的地理偏见
• mode -出行方式：“开车”、“步行”、“骑自行车”、“公交”

空间滤波器

Geoapify支持强大的空间过滤：

# Rectangular area
"filter": "rect:west,south,east,north"

# Circular area  
"filter": "circle:lon,lat,radius_meters"

# Country restriction
"filter": "countrycode:us,ca"

# Combined filters
"filter": "rect:-74.1,40.7,-73.9,40.8|countrycode:us"

错误处理

服务器提供全面的错误处理：

• 验证错误 坐标无效或缺少参数
• API错误 来自Geoapify的详细信息
• 网络错误 带有重试建议
• 费率限制处理 带有清晰的错误信息

🧪 发展

运行测试

# Run all tests
uv run python test_server.py

# Test specific functionality
uv run python -c "
from geoapify_mcp_server.server import load_tool_schemas, TOOL_FUNCTIONS
print(f'Loaded {len(load_tool_schemas())} tools')
print(f'Mapped {len(TOOL_FUNCTIONS)} functions')
"

项目结构

geoapify-mcp-server/
├── geoapify_mcp_server/
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Entry point
│   ├── server.py            # MCP server implementation
│   ├── handlers.py          # Tool implementations
│   └── tools.json           # Tool schemas
├── test_server.py           # Test suite
├── test_cases.json          # Test definitions
├── main.py                  # Compatibility wrapper
├── pyproject.toml           # Project configuration
├── .env.example             # Environment template
└── README.md                # This file

添加新工具

1. 将工具架构添加到 geoapify_mcp_server/tools.json
2. 在中实现处理程序功能 geoapify_mcp_server/handlers.py
3. 添加功能 TOOL_FUNCTIONS 映射
4. 在中创建测试用例 test_cases.json
5. 运行测试以验证

📊 支持的API

此服务器实现 14个核心Geoapify API:

🎯 用例

非常适合需要以下条件的应用程序：

• 地址验证和标准化
• 基于位置的搜索和发现
• 路线规划和优化
• 交付和物流管理
• 地理数据分析
• 房地产和地图应用程序
• 旅行和导航服务
• 位置智能和洞察力

🔒 安全与隐私

• API密钥安全存储在环境变量中
• 没有数据持久性或敏感信息记录
• 所有直接向Geoapify的安全API发出的请求
• 遵循MCP安全最佳实践

📝 许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📞 支持

• 对API进行Geoapify问题: Geoapify文档
• MCP服务器问题：在GitHub上打开一个问题
• 功能请求：打开带有增强标签的问题

🙏 致谢

• Geoapify 提供卓越的位置API
• 模型上下文协议 对于MCP规范
• 开源社区提供持续的灵感