alltrails-mcp

AllTrails MCP

一个 模型上下文协议 服务，可将 Claude 连接到 AllTrails，让你通过自然语言搜索步道、查看步道详情、评论、照片和天气，以及访问自己保存的列表和徒步历史记录。

警告

由 AI 开发的项目。 此代码库完全由 Claude 构建并积极维护。没有人类审查过其实现。使用前请检查所有代码和工具权限。

注意

非官方且不受支持。 AllTrails 没有公开 API。此服务通过逆向工程获取 alltrails.com 使用的内部 API。该 API 由 DataDome 机器人防护机制保护，并受 AllTrails 服务条款约束。它可能在没有通知的情况下失效，自动访问也可能违反其服务条款——此前一个第三方 AllTrails 项目应 AllTrails 要求而被禁用。请自行决定是否使用，且仅用于自己的账户。

你可以做什么

向 Claude 提出这类问题：

• “查找俄勒冈州波特兰附近有瀑布的步道”
• “步道 10236086 在 AllTrails 上的评分和长度是多少？”
• “总结这条步道的近期评论”
• “我标记为已完成的步道有哪些？”
• “显示我保存的‘周末徒步’列表中的步道”

要求

• Claude Desktop（或任何 MCP 宿主）
• Node.js 22.5 或更高版本
• ContextMint Bridge 浏览器扩展，以及一个已登录 alltrails.com 的标签页（参见身份验证）

服务条款确认

使用此 MCP 服务，即表示你确认并同意以下内容：

1. 此服务使用你自己的已登录会话访问 AllTrails。 它会复用你自己浏览器会话中的 Cookie；无法访问其他人的账户或私人数据。

2. AllTrails 服务条款约束你对本服务的使用，就如同约束你直接使用 AllTrails 一样。AllTrails 限制自动访问和抓取，并为其 API 提供机器人防护。通过此服务进行自动化使用可能违反这些条款。每次调用工具，即表示你同意 AllTrails 的条款。

3. 仅供个人使用。 此项目与 AllTrails, LLC 无关联，也未获其认可或赞助。它是一款个人自动化工具。请勿将其用于批量提取 AllTrails 数据、构建竞争产品，或以任何会给其服务造成负担的方式使用。

4. 你需对任何后果承担全部责任——无论是技术方面（速率限制、CAPTCHA 验证、账户处置）还是其他方面。维护者不提供任何担保或支持。

本节是维护者本着诚信所作的概要说明——不构成法律建议，也不会修改或取代 AllTrails 的实际服务条款。

安装

1. 克隆并构建

git clone https://github.com/chrischall/alltrails-mcp.git
cd alltrails-mcp
npm install
npm run build

2. 添加到 Claude Desktop

编辑 Claude Desktop 配置文件：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

在 "mcpServers" 中添加 alltrails 项（如果该键不存在，请创建它）：

{
  "mcpServers": {
    "alltrails": {
      "command": "node",
      "args": ["/absolute/path/to/alltrails-mcp/dist/index.js"]
    }
  }
}

将 /absolute/path/to/alltrails-mcp 替换为克隆仓库的路径。

3. 重启 Claude Desktop

完全退出（Mac 上按 Cmd+Q，而非仅关闭窗口），然后重新启动。

4. 验证

询问 Claude：“搜索 AllTrails，查找我附近的步道。”

身份验证

AllTrails 通过 DataDome 机器人防护机制保护其内部 API，而 DataDome 会对 HTTP 客户端本身进行指纹识别——从浏览器复制 cookie，再通过 Node 重放，即使浏览器能顺利通过，也会被拒绝。因此，fetchproxy 桥接程序是必需的：每个 API 请求都会在你已登录的 alltrails.com 标签页中，以同源 fetch 的方式执行，并复用你的已验证会话。没有存储 cookie 的模式。

要求：安装 ContextMint Bridge 浏览器扩展（Chrome：从发布页面下载 chrome zip 并以未打包的方式加载——目前请使用 Chrome；Safari 支持将随 ContextMint 应用一同发布，目前尚无公开下载版本）、打开一个已登录的 alltrails.com 标签页，并在首次使用时通过一次性配对码审批（信任状态会保留）。

ContextMint Bridge 是 fetchproxy 浏览器扩展的新名称，由同一位维护者开发——fetchproxy 自己的 README（https://github.com/chrischall/fetchproxy#extension）中也指向它。其源代码公开于 https://github.com/nullnet-app/contextmint-bridge：你可以自行构建，或使用旁边发布的 .sha256 文件校验发布版 zip（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

AllTrails 自有客户端发送的 x-at-key 应用密钥绝不会存储在此仓库或你的配置中——服务器会在首次需要时从你标签页自身的 API 流量中捕获实时值，仅保存在内存中；如果 AllTrails 轮换该密钥，服务器会自动重新捕获。alltrails_healthcheck 工具会通过桥接程序往返发送探测请求，并告知你哪个环节出了问题。

配置

环境变量	必填	用途
ALLTRAILS_USER_ID	否	用于按用户提供的工具的数字用户 ID；默认通过 /api/alltrails/me 获取已登录用户。
ALLTRAILS_WS_PORT	否	fetchproxy 集中器端口（默认 37149，由整个 fetchproxy 集群共享——仅在本地开发或测试时覆盖）。
ALLTRAILS_LOCALE / ALLTRAILS_CALLER	否	覆盖对应的请求标头。
ALLTRAILS_REQUEST_TIMEOUT_MS	否	每个请求的超时时间，单位为 ms（默认 30000），适用于两种路径。
ALLTRAILS_DEBUG_LOG	否	设为 1/true/yes/on 时，会将每个请求/响应记录到 stderr——包括方法、路径、状态、响应大小，以及经过脱敏处理的 200 字符请求正文前缀（绝不会记录响应正文）。

可用工具

所有工具均为只读——此服务绝不会向 AllTrails 写入数据。

工具	功能
alltrails_search	按路线或地点名称搜索 AllTrails——自由文本查询使用与 alltrails.com 搜索框相同的建议端点（types: ["trail"] 可将结果限定为路线）
alltrails_resolve_location	将地点名称解析为 AllTrails 地点记录（国家／州／城市／区域／兴趣点），并提供每条记录的类型、坐标、slug 和消歧标签
alltrails_get_trail	路线详情——名称、概览、长度、爬升高度、难度、评分、路线类型、位置（detail：basic/medium/offline 用于选择 AllTrails 发送给我们的内容）
alltrails_get_trail_reviews	路线的用户评价——每条包含 {user, rating, comment}
alltrails_get_trail_photos	路线照片——精简记录，包含可获取图片的 url
alltrails_get_trail_gpx	将路线导出为 GPX 1.1 格式（轨迹点 + 海拔）
alltrails_get_trail_weather	路线天气概览
alltrails_get_profile	已登录用户的个人资料
alltrails_list_user_lists	用户保存的列表／收藏
alltrails_get_list_items	根据列表 ID 获取列表中保存的路线——按顺序返回 {trailId, type, order, notes, addedAt}，通过 get_trail 补全每条路线的信息
alltrails_list_completed_trails	用户已完成的路线
alltrails_get_activity_feed	用户的动态（feed：local/timeline/personal 用于指定动态条目，省略则返回目录；cursor 用于分页）
alltrails_healthcheck	通过 fetchproxy 桥接执行一次往返探测，并报告角色／端口／耗时，以及说明故障环节的通俗提示

面向用户的工具默认使用已登录用户（通过 /api/alltrails/me 或 ALLTRAILS_USER_ID 解析）；传入 userId 可指定公开个人资料。

响应形式：view

alltrails_search、alltrails_get_trail、alltrails_get_trail_reviews、 alltrails_get_trail_photos、alltrails_get_list_items 和 alltrails_get_activity_feed 均接受一个 view 参数，提供两个级别：

view	返回内容
compact	默认值。 上表所述的精简投影——调用方会用到的字段。无需传入参数。
full	AllTrails 完整且未经修改的记录。

默认采用精简形式是有意为之。这些投影原本就已存在，只是藏在 compact: false 后面，并要求工具说明调用方主动选择——而需要主动请求的效率优化通常不会被采用。需要投影中省略的字段时，请指定 view: "full"；最常见的情况是从 alltrails_get_trail 获取路线几何数据。

view 不等于 detail。 alltrails_get_trail 还接受 detail（basic/medium/offline），它是直接传递给 AllTrails 的参数—— 决定 API 发送给我们什么内容。view 则决定此服务交给你什么内容。路线几何数据需要同时设置两者：用 detail: "offline" 获取数据，再用 view: "full" 保留数据。参数名统一为 view，正是为了避免混淆。

有一种投影并非子集：alltrails_get_trail_photos 的 url 由精简级别派生（AllTrails 的记录不包含图片 URL），因此 view: "full" 不会包含它。

故障排除

403 Forbidden — AllTrails 的 DataDome 防护拒绝了请求。这通常意味着标签页尚未登录（或 DataDome 正在对其进行验证）——在已打开的标签页中登录 alltrails.com，然后重试。

“AllTrails bridge: …” — 在请求到达 AllTrails 之前，桥接本身就发生了故障（扩展程序未运行、配对未获批准或没有标签页）。运行 alltrails_healthcheck 进行诊断，并检查 ContextMint Bridge 扩展程序弹出窗口。

“AllTrails: capturing the x-at-key app key failed…” — 工具会在调用等待期间，从标签页发出的请求中读取密钥；空闲标签页不会发出请求。先刷新并无帮助：扩展程序只会在调用期间监听，因此如果刷新在调用开始前就已完成，当时并没有监听。再次运行该工具，并在运行期间刷新已登录的 www.alltrails.com 标签页。

结果为空或出乎意料 — AllTrails 的内部端点未公开文档，且会随时间变化；响应可能有所变动。设置 ALLTRAILS_DEBUG_LOG=1，即可在 stderr 中跟踪每个请求的方法、路径、状态和响应大小。

开发

npm test         # run the vitest suite
npm run build    # tsc → dist/, then esbuild bundle → dist/bundle.js
npm run dev      # node --env-file=.env dist/index.js (requires built dist)

vitest.config.ts 对 src/** 强制要求 100% 覆盖率（stdio 入口点除外）。Main 受保护——所有更改都必须通过 PR 合并。完整的 PR 和发布流程请参阅 CLAUDE.md。

项目结构

src/
  index.ts          MCP server entry (runMcp + StdioServerTransport)
  protocol.ts       Wire-level constants (BASE_URL, app key, headers)
  transport.ts      createAllTrailsTransport(): the fetchproxy bridge transport
  client.ts         AllTrailsClient — bridge requests, live x-at-key capture, 429 retry
  config.ts         Env parsing (api key, headers, timeout, port, user id, debug)
  validate.ts       parseAllTrails(): zod validation of responses at call sites
  tools/
    _shared.ts      Response helpers + resolveUserId
    trails.ts       get_trail, reviews, photos, weather, gpx export
    explore.ts      search, list by state/country
    user.ts         profile, saved lists, completed trails, activity feed
    healthcheck.ts  alltrails_healthcheck (bridge diagnostics)
tests/              Mirrors src/; mocks AllTrailsClient.request via vi.spyOn

请求流程

每个 API 请求都会通过 fetchproxy 桥接（src/transport.ts 中共享的 createFetchproxyTransport 工厂），在已登录的 alltrails.com 标签页内以同源 fetch 的方式执行。浏览器会携带自身的 Cookie；服务端只会附加 AllTrails 协议标头（x-at-key 等），而标签页内的 fetch 不会自行添加这些标头。没有直接通过 Node 发起请求的模式——DataDome 会对 HTTP 客户端进行指纹识别，因此只有在标签页内发起的请求才可靠。

有关如何安装 ContextMint Bridge 扩展程序，请参阅身份验证。

许可证

MIT