内容
# Neshan MCP 服务器
借助这个项目，像 **Claude Desktop** 或 **Cursor** 这样的 AI 助手可以访问 [Neshan](https://platform.neshan.org) 的地图功能 — 也就是说，你可以直接在聊天中告诉它们 *「从我家到工作地点的路线，显示实时交通情况」* 或 *「这个坐标附近最近的咖啡馆在哪里？」* 然后立即看到答案。
这个项目是一个 [MCP 服务器](https://modelcontextprotocol.io)：一个标准接口，它以 AI 助手可以自行决定使用的方式提供 Neshan 服务。
## 可以完成哪些任务？
连接此服务器到您的 AI 助手后，您可以用自然语言请求：
- **地点搜索** — 通过名称或描述查找地址、商家或地点
- **地址与坐标转换** — 通过地理坐标获取地址或反之亦然
- **路线规划** — 为汽车、摩托车或行人规划两点或多点之间的路线，考虑实时交通、无交通或历史模式
- **多站点路线优化（TSP）** — 多个目的地访问的最佳顺序
- **路线与道路匹配** — 将原始 GPS 点序列转换为实际道路路线
- **可达区域（Isochrone）** — 指定从某个点在特定时间/距离内可达的区域
- **距离/时间矩阵** — 同时获取多个起点和终点之间的距离和旅行时间
- **车队路线规划（VRP）** — 在考虑容量和时间窗口的情况下，将订单优化分配给多个车辆
- **静态地图** — 获取某个点的地图图像，或显示起点和终点之间路径的地图
- **交互式地图** — 创建带有标记和路径的地图页面，可在浏览器中打开
- **交通分析** — 过去 24 小时内某个区域的交通状况
- **地点详情** — 获取搜索结果的完整信息（地址、分类、社区）
所有这些都通过与 AI 助手的自然对话实现；您无需了解 API 或端点的详细信息。
## 最快捷的方式：使用现成的服务器
无需安装或运行任何东西 — 只需将其添加到您的客户端设置中（Claude Desktop，Cursor 等）：
```json
{
"mcpServers": {
"neshan": {
"type": "http",
"url": "https://platform-stage.rajman.org/mcp",
"headers": { "Neshan-Api-Key": "您的_API_密钥" }
}
}
}
```
> 现成服务器地址：`https://platform-stage.rajman.org/mcp`
从 [Neshan 控制面板](https://platform.neshan.org) 获取您的 API 密钥（参见「获取和设置 API 密钥」部分）。就这样 — 您的 AI 助手现在可以访问 Neshan 的地图功能。
如果您更喜欢在自己的系统/服务器上运行服务器，请继续阅读本指南。
## 运行服务器所需的条件
1. **Python 3.10 或更高版本**
2. **Neshan API 密钥** — 在 [platform.neshan.org](https://platform.neshan.org) 注册并获取您所需的服务密钥（开始使用时免费）
3. 以下客户端之一：Claude Desktop，Cursor，或其他支持 MCP 的客户端
## 安装
```bash
pip install -e .
```
## 获取和设置 API 密钥
从 [Neshan 控制面板](https://platform.neshan.org) 获取您的密钥，然后选择以下方法之一：
**方法 1 — .env 文件（最简单的方式，推荐 Claude Desktop 使用）：**
```bash
cp .env.example .env
# 在 .env 文件中用您的密钥替换 NESHAN_API_KEY
```
**方法 2 — 在请求头中发送密钥（适用于 HTTP）：**
如果您以 HTTP 方式运行服务器，您可以在每个连接中发送密钥，无需 .env 文件（参见「连接客户端」部分）。
## 运行服务器
```bash
neshan-mcp # 默认模式，适用于 Claude Desktop / Cursor
```
或使用 Docker：
```bash
docker build -t neshan-mcp .
docker run -p 3000:3000 --env-file .env neshan-mcp
```
## 连接到 Claude Desktop
打开 Claude Desktop 的配置文件并添加：
```json
{
"mcpServers": {
"neshan": {
"command": "neshan-mcp",
"env": { "NESHAN_API_KEY": "您的_API_密钥" }
}
}
}
```
重启 Claude Desktop — 现在您可以直接询问有关地图、路线和地址的问题。
## 通过 HTTP 连接（Cursor 或其他客户端）
如果您使用 `neshan-mcp-http` 运行服务器：
```json
{
"mcpServers": {
"neshan": {
"type": "http",
"url": "http://localhost:3000/mcp",
"headers": { "Neshan-Api-Key": "您的_API_密钥" }
}
}
}
```
## 常见问题
**API 密钥是否免费？**
Neshan 提供一个免费的起始计划；如果您需要更多使用额度，您可以根据 [platform.neshan.org](https://platform.neshan.org) 上的计划进行升级。
**我可以只启用部分服务吗？**
是的 — 对于每个服务（搜索、路由、静态地图等），您可以获取一个单独的密钥并进行单独的设置；只需在 `.env` 文件中设置 `NESHAN_KEY_<SERVICE>`（例如 `NESHAN_KEY_STATIC`）。
**我收到与密钥相关的错误，应该怎么办？**
请确保您正确复制了密钥，并且在 Neshan 控制面板中，您没有为请求的 IP 地址/域名设置限制。
## 文档和支持
- Neshan API 完整文档：https://platform.neshan.org/docs
