内容
# Komoot MCP 服务器
一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，为 Claude 等 AI 助手提供 Komoot 访问权限。浏览、搜索和下载旅游路线；上传新活动；使用 OpenRouteService 规划路线，并通过自然语言进行地理编码 — 所有这些都可以通过该服务器实现。
服务器运行在两种模式下：
* **本地标准输入输出**，适用于单用户模式，凭证存储在环境变量中。
* **可流式传输的 HTTP**，位于 Eric AI 平台网关后面，网关在每个请求中转发每个用户的凭证，因此一个服务器进程可以安全地为多个租户提供服务。
## 功能
- **浏览和搜索**您的 Komoot 旅游路线，支持丰富的筛选（运动类型、可见性、排序）
- **下载旅游路线**为 GPX 文件
- **上传活动**到 Komoot（GPX、FIT、TCX），支持可配置的运动类型
- **AI 辅助路线规划**，通过 OpenRouteService，支持运动特定配置文件、 trails/道路偏好、环形支持和航点
- **地理编码**，通过 Komoot 的 Photon API（免费，无需 API 密钥）
- **管理旅游路线** — 修改元数据和删除旅游路线
## 安装
```bash
pip install komoot-mcp-server
```
或从源代码安装：
```bash
git clone https://github.com/marcodetering-prog/komoot-mcp-server.git
cd komoot-mcp-server
pip install -e .
```
## 配置
### 本地 / 标准输入输出模式
在标准输入输出模式下，凭证来自环境变量。
| 变量 | 描述 |
|---|---|
| `KOMOOT_EMAIL` | 您的 Komoot 账户电子邮件地址 |
| `KOMOOT_PASSWORD` | 您的 Komoot 账户密码 |
| `ORS_API_KEY` | 可选的 [OpenRouteService API 密钥](https://openrouteservice.org) — 启用 `komoot_plan_route` 工具 |
| `KOMOOT_DATA_DIR` | _废弃。_ 以前用于在服务器文件系统上暂存 GPX 文件。GPX 工具现在在工具响应中直接返回内容（参见 [问题 #9](https://github.com/Eric-AI-M/komoot-mcp-server/issues/9)）；此变量被接受以保持兼容性，但未使用。 |
| `KOMOOT_RATE_LIMIT` | 向 Komoot 发送请求的每秒限制。默认 `2` |
### 平台集成模式（Eric AI 网关）
使用 `--transport http` 运行服务器。网关通过头部注入凭证 — **无需环境变量存储 `KOMOOT_EMAIL` / `KOMOOT_PASSWORD`**。
| 头部 | 目的 |
|---|---|
| `X-User-Credentials` | JSON 对象 `{"email": "user@example.com", "password": "...", "ors_api_key": "..."}`。每个请求解析，用于构建请求范围内的 `AuthManager` 和（可选）租户特定的 `RoutingManager`，响应发送后丢弃。`ors_api_key` 为可选 — 仅在用户调用 `komoot_plan_route` 时需要。 |
| `X-Internal-Secret` | 当服务器设置 `INTERNAL_SECRET` 环境变量时，每个非 `/health` 请求必须包含匹配的值，否则拒绝并返回 401。 |
每个请求都通过 `contextvars.ContextVar` 获取自己的 `AuthManager` + `KomootClient`，因此并发用户永远不会看到对方的凭证。用于 `komoot_plan_route` 的 OpenRouteService API 密钥通过与 `X-User-Credentials` JSON 负载相同的请求作用域凭证流动 — 不需要在 HTTP 模式下设置进程范围的 ORS 密钥。
如果同时存在环境变量和 `X-User-Credentials` 头部，则头部优先。对于 `ORS_API_KEY`，仅在请求未转发 `ors_api_key` 时（主要是 stdio/本地开发）才会使用环境变量作为备用。
## 与 Claude 一起使用
将以下内容添加到您的 Claude 配置（`claude_desktop_config.json` 或 `.claude/mcp.json`）：
```json
{
"mcpServers": {
"komoot": {
"command": "python",
"args": ["-m", "komoot_mcp.server"],
"env": {
"KOMOOT_EMAIL": "your-email@example.com",
"KOMOOT_PASSWORD": "your-password",
"ORS_API_KEY": "your-ors-api-key"
}
}
}
}
```
连接后，您可以向 Claude 提问：
- "显示我的最近的徒步旅行路线"
- "下载路线 12345 为 GPX 文件"
- "计划从柏林开始的 10 公里环形跑步路线"
- "将 GPX 文件上传到 Komoot"
- "地理编码 'Marienplatz Munich'"
- "路线 12345 有哪些道路类型和表面？"
## 可用工具（35）
### 身份验证
| 工具 | 描述 |
|---|---|
| `komoot_login` | 与 Komoot 进行身份验证。在平台模式下，网关通过头部提供凭证；在 stdio 模式下，使用环境变量。 |
### 浏览和搜索
| 工具 | 描述 |
|---|---|
| `komoot_list_tours` | 列出您的旅游路线，支持按运动类型、可见性、名称搜索、排序和分页筛选 |
| `komoot_get_tour` | 获取特定旅游路线的完整详细信息（距离、海拔、时长、难度） |
| `komoot_get_tour_full` | 在一次调用中获取旅游路线的完整信息 — 替代 5 次以上的链式调用。返回名称、运动类型、距离、海拔、表面/道路类型分解、方向步骤数和任何时间线高亮 ID（使用 `komoot_get_highlight` 解析）。 |
| `komoot_get_tour_photos` | 获取附加到旅游路线的封面/照片图像（渲染模板化的 URL，宽度为 800） |
| `komoot_get_tour_line` | 获取旅游路线的简化线条几何形状（轻量级替代坐标） |
| `komoot_get_highlight` | 通过 ID 解析 Komoot 高亮（POI）。返回名称、类别、运动类型、位置。传递 `include_tips=True` 以获取社区提示，并传递 `include_recommenders=True` 以获取推荐者计数。 |
| `komoot_list_user_highlights` | 列出用户的保存的高亮（POI） |
| `komoot_tour_weather` | 获取旅游路线的天气预报（实验性 — 端点签名可能需要运行时验证）。访问 Komoot 的专用天气-沿-旅游服务。 |
| `komoot_get_user_profile` | 检索您的 Komoot 配置文件信息 |
### 旅游数据
| 工具 | 描述 |
|---|---|
| `komoot_get_tour_coordinates` | 获取旅游路线的坐标数组（纬度，经度，海拔） |
| `komoot_get_tour_gpx` | 在工具响应中直接返回旅游路线的 GPX 内容，作为围栏的 `xml` 代码块。超大正文会被截断；始终报告完整的字节数。 |
| `komoot_get_tour_directions` | 获取旅游路线的逐向指示 |
| `komoot_get_tour_way_types` | 获取道路类型分解（道路、 trails、路径百分比） |
| `komoot_get_tour_surfaces` | 获取表面分解（铺装、碎石、 trails百分比） |
| `komoot_get_tour_timeline` | 获取旅游路线的时间线 |
> FIT 导出（`komoot_get_tour_fit`）已被删除 — kompy 不支持生成 FIT 文件。请改用 GPX 导出。
### 高亮（POI）
| 工具 | 描述 |
|---|---|
| `komoot_get_highlight_images` | 获取附加到 Komoot 高亮的照片 |
| `komoot_get_highlight_tips` | 获取 Komoot 高亮的社区提示 |
### 收藏
| 工具 | 描述 |
|---|---|
| `komoot_get_collection` | 获取 Komoot 收藏的元数据 |
| `komoot_get_collection_tours` | 列出收藏中的旅游路线 |
### 分享
| 工具 | 描述 |
|---|---|
| `komoot_create_share_link` | 创建公共分享链接（返回令牌 + URL） |
| `komoot_revoke_share_link` | 撤销旅游路线的分享令牌 |
| `komoot_resolve_share_url` | 解析 Komoot 分享 URL 为旅游路线元数据（当分享令牌存在时，无需身份验证） |
### 写操作
| 工具 | 描述 |
|---|---|
| `komoot_upload_tour` | 上传 GPX、FIT 或 TCX 文件为新的 Komoot 旅游路线。传递 `sport=` 以选择活动类型（默认 `touringbicycle`）。 |
| `komoot_modify_tour` | 修改旅游路线的元数据（名称、运动类型、可见性） |
| `komoot_modify_tour_extended` | 修改扩展的旅游路线元数据（描述、装备、日期、名称、运动类型、状态）— 比 `komoot_modify_tour` 更广泛的覆盖范围 |
| `komoot_delete_tour` | 永久删除旅游路线 |
### 发现
| 工具 | 描述 |
|---|---|
| `komoot_recommend_tours_near` | 通过 umbrella `/discover/{lat,lng}/elements/` 端点发现附近的混合包（旅游路线、智能旅游路线、收藏）。可选的运动筛选。 |
| `komoot_smart_tours_near` | 仅在某个点附近发现智能旅游路线（使用 `/discover_tours/from_location/`）。比 `komoot_recommend_tours_near` 更窄 — 仅限智能旅游路线，不包括收藏。 |
| `komoot_smart_tour_for_highlight` | 经过特定高亮（POI）的智能旅游路线。需要高亮附近的 `lat`/`lng` — 即使有高亮 ID，Komoot 的 API 也需要一个位置。 |
| `komoot_discover_with_attributes` | 发现附近的旅游路线，按路线属性筛选（例如 `waterfalls`、`lakes_rivers`）。 |
| `komoot_route_attribute_options` | 列出给定 `(lat, lng, sport, max_distance)` 上下文的合法路线属性名称。在调用 `komoot_discover_with_attributes` 之前先调用此函数以选择属性。 |
### 路线规划和地理编码
| 工具 | 描述 |
|---|---|
| `komoot_geocode` | 使用 Komoot 的 Photon API 进行地理编码或反向地理编码 |
| `komoot_plan_route` | 使用 OpenRouteService 规划路线，支持运动配置文件、 trails/道路偏好、环形支持和可选航点。直接在响应中返回 GPX 内容（以 Komoot 兼容的轨迹格式），因此调用者可以直接保存或转发。 |
| `komoot_plan_and_upload` | 通过 OpenRouteService 规划路线并将其上传到 Komoot，是一项服务器端操作。返回新的旅游路线 ID 和 URL — 无需在对话中传输 ~100k 个 GPX 令牌。 |
#### 运动配置文件
`komoot_plan_route` 工具支持以下运动配置文件，每个配置文件都映射到 OpenRouteService 路线配置文件：
| 运动 | ORS 配置文件 |
|---|---|
| `hike` | foot-hiking |
| `trail_run` | foot-walking |
| `mountain_bike` | cycling-mountain |
| `road_cycle` | cycling-road |
| `gravel_ride` | cycling-regular |
## 依赖
- Python >= 3.11
- [mcp](https://pypi.org/project/mcp/) — MCP 框架
- [kompy](https://pypi.org/project/kompy/) — Komoot API 客户端（固定 `<0.1.0`；我们依赖于几个 `Tour._create_*` 内部函数）
- [gpxpy](https://pypi.org/project/gpxpy/) — 上传 GPX 文件的 GPX 解析
- [openrouteservice](https://pypi.org/project/openrouteservice/) — OpenRouteService 客户端（可选，用于路线规划）
## 许可证
该项目按原样提供。有关许可证详细信息，请参阅存储库。
## 链接
- [GitHub 存储库](https://github.com/marcodetering-prog/komoot-mcp-server)
- [MCP 协议文档](https://modelcontextprotocol.io)
- [OpenRouteService](https://openrouteservice.org)
