Geoapify MCP Server

一个基于Geoapify API的MCP (Model Context Protocol) 服务器，提供地理编码、路线规划、地点搜索等位置服务。

功能特性

- 🗺️ 地理编码: 地址转坐标，坐标转地址
- 🚗 路线规划: 多种交通方式的路线计算
- 📍 地点搜索: 按类别搜索POI和兴趣点
- 🔍 地址自动补全: 实时地址建议
- 📊 等时线分析: 可达性区域计算
- 🏢 地点详情: 获取详细的地点信息
- 💾 智能缓存: Redis/内存缓存支持
- 🔒 安全认证: API密钥和IP白名单
- 📝 完整日志: 结构化日志记录
- 🐳 容器化: Docker和Docker Compose支持

快速开始

$3

1. 访问 Geoapify官网
2. 注册账户并创建项目
3. 获取API密钥（免费计划每天3000次调用）

$3

``bash

`克隆项目`


git clone 
cd geoapify-mcp-server
安装依赖

npm install
配置环境变量

cp .env.example .env
编辑.env文件，填入你的Geoapify API密钥
启动开发服务器

npm run dev

$3

`bash

`构建镜像`


docker build -t geoapify-mcp .
运行容器

docker run -p 50001:50001 --env-file .env geoapify-mcp

$3

`bash

`启动完整服务栈（包含Redis和Nginx）`


docker-compose up -d


环境变量配置

`bash

`必需配置`


GEOAPIFY_API_KEY=your_geoapify_api_key_here
可选配置

PORT=50001
NODE_ENV=development
MCP_API_KEY=your_mcp_server_api_key_here
REDIS_URL=redis://localhost:6379
LOG_LEVEL=info
RATE_LIMIT_MAX=100
ALLOWED_ORIGINS=*
ALLOWED_IPS=*


API端点
$3


GET /health

$3


GET /tools

$3


POST /tools/{toolName}
Content-Type: application/json
X-API-Key: your_mcp_api_key

{ "arguments": { // 工具参数 } }`

`$3`

#### 地理编码`POST /geocode { "address": "北京市朝阳区", "options": { "country": "cn", "language": "zh" } }`

#### 反向地理编码`POST /reverse-geocode { "lat": 39.9042, "lon": 116.4074, "options": { "language": "zh" } }`

#### 路线规划`POST /routing { "waypoints": ["39.9042,116.4074", "31.2304,121.4737"], "mode": "drive", "options": { "type": "balanced", "details": "instruction_details" } }`

#### 地点搜索`POST /places { "categories": "catering.restaurant", "filter": "circle:116.4074,39.9042,1000", "options": { "limit": 20, "language": "zh" } }`

`支持的MCP工具`

1. geocode_address - 地址地理编码 2. reverse_geocode - 反向地理编码 3. calculate_route - 路线计算 4. search_places - 地点搜索 5. address_autocomplete - 地址自动补全 6. calculate_isoline - 等时线计算 7. get_place_details - 地点详情

`部署选项`

`$3`

#### Heroku`bash

`安装Heroku CLI`


heroku create your-app-name
heroku config:set GEOAPIFY_API_KEY=your_key
git push heroku main


#### AWS Lambda
使用Serverless Framework或AWS SAM部署

#### Google Cloud Run`bash gcloud run deploy geoapify-mcp \ --source . \ --platform managed \ --region asia-east1 \ --set-env-vars GEOAPIFY_API_KEY=your_key`

`$3`

`bash

`使用PM2管理进程`


npm install -g pm2
pm2 start src/server.js --name geoapify-mcp
pm2 startup
pm2 save

$3

参考 k8s/ 目录中的配置文件

`性能优化`

- 缓存策略: 地理编码结果缓存1小时，路线缓存30分钟 - 速率限制: 默认每15分钟100次请求 - 连接池: 复用HTTP连接 - 压缩: 启用gzip压缩 - 日志轮转: 自动日志文件管理

`监控和日志`

- 日志文件位置: logs/- 健康检查:GET /health- 错误追踪: 结构化错误日志 - 性能指标: 请求时间和成功率

`安全考虑`

- API密钥验证 - IP白名单支持 - 速率限制 - HTTPS强制（生产环境） - 输入验证和清理 - 安全头设置

`故障排除`

`$3`

1. API密钥错误 - 检查.env 文件中的 GEOAPIFY_API_KEY- 确认密钥有效且未过期

2. Redis连接失败 - 检查Redis服务是否运行 - 验证连接配置

3. 速率限制 - 检查Geoapify账户配额 - 调整本地速率限制设置

`$3`

`bash

`查看实时日志`


tail -f logs/combined.log
查看错误日志

tail -f logs/error.log
Docker日志

docker logs geoapify-mcp-server


开发指南
$3

1. 在 src/handlers/mcpHandler.js中定义工具 2. 在src/services/geoapifyService.js中实现API调用 3. 添加输入验证和错误处理 4. 更新文档

`$3`

`bash

`运行测试`


npm test
测试覆盖率

npm run test:coverage

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

支持

如有问题，请联系：
- 邮箱: your-email@example.com
- GitHub Issues: [项目地址]

Geoapify MCP Server

一个基于Geoapify API的MCP (Model Context Protocol) 服务器，提供地理编码、路线规划、地点搜索等位置服务。

功能特性

快速开始

$3

1. 访问 Geoapify官网
2. 注册账户并创建项目
3. 获取API密钥（免费计划每天3000次调用）

$3

``bash

`克隆项目`


git clone 
cd geoapify-mcp-server
安装依赖

npm install
配置环境变量

cp .env.example .env
编辑.env文件，填入你的Geoapify API密钥
启动开发服务器

npm run dev

$3

`bash

`构建镜像`


docker build -t geoapify-mcp .
运行容器

docker run -p 50001:50001 --env-file .env geoapify-mcp

$3

`bash

`启动完整服务栈（包含Redis和Nginx）`


docker-compose up -d


环境变量配置

`bash

`必需配置`


GEOAPIFY_API_KEY=your_geoapify_api_key_here
可选配置

PORT=50001
NODE_ENV=development
MCP_API_KEY=your_mcp_server_api_key_here
REDIS_URL=redis://localhost:6379
LOG_LEVEL=info
RATE_LIMIT_MAX=100
ALLOWED_ORIGINS=*
ALLOWED_IPS=*


API端点
$3


GET /health

$3


GET /tools

$3


POST /tools/{toolName}
Content-Type: application/json
X-API-Key: your_mcp_api_key

{ "arguments": { // 工具参数 } }`

`$3`

#### 地理编码`POST /geocode { "address": "北京市朝阳区", "options": { "country": "cn", "language": "zh" } }`

#### 反向地理编码`POST /reverse-geocode { "lat": 39.9042, "lon": 116.4074, "options": { "language": "zh" } }`

#### 路线规划`POST /routing { "waypoints": ["39.9042,116.4074", "31.2304,121.4737"], "mode": "drive", "options": { "type": "balanced", "details": "instruction_details" } }`

#### 地点搜索`POST /places { "categories": "catering.restaurant", "filter": "circle:116.4074,39.9042,1000", "options": { "limit": 20, "language": "zh" } }`

`支持的MCP工具`

`部署选项`

`$3`

#### Heroku`bash

`安装Heroku CLI`


heroku create your-app-name
heroku config:set GEOAPIFY_API_KEY=your_key
git push heroku main


#### AWS Lambda
使用Serverless Framework或AWS SAM部署

#### Google Cloud Run`bash gcloud run deploy geoapify-mcp \ --source . \ --platform managed \ --region asia-east1 \ --set-env-vars GEOAPIFY_API_KEY=your_key`

`$3`

`bash

`使用PM2管理进程`


npm install -g pm2
pm2 start src/server.js --name geoapify-mcp
pm2 startup
pm2 save

$3

参考 k8s/ 目录中的配置文件

`性能优化`

`监控和日志`

- 日志文件位置: logs/- 健康检查:GET /health- 错误追踪: 结构化错误日志 - 性能指标: 请求时间和成功率

`安全考虑`

- API密钥验证 - IP白名单支持 - 速率限制 - HTTPS强制（生产环境） - 输入验证和清理 - 安全头设置

`故障排除`

`$3`

1. API密钥错误 - 检查.env 文件中的 GEOAPIFY_API_KEY- 确认密钥有效且未过期

2. Redis连接失败 - 检查Redis服务是否运行 - 验证连接配置

3. 速率限制 - 检查Geoapify账户配额 - 调整本地速率限制设置

`$3`

`bash

`查看实时日志`


tail -f logs/combined.log
查看错误日志

tail -f logs/error.log
Docker日志

docker logs geoapify-mcp-server


开发指南
$3

1. 在 src/handlers/mcpHandler.js中定义工具 2. 在src/services/geoapifyService.js中实现API调用 3. 添加输入验证和错误处理 4. 更新文档

`$3`

`bash

`运行测试`


npm test
测试覆盖率

npm run test:coverage

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

支持

如有问题，请联系：
- 邮箱: your-email@example.com
- GitHub Issues: [项目地址]