{
  "markdown": "# AllTrails MCP\n\n[![CI](https://github.com/chrischall/alltrails-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/alltrails-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/alltrails-mcp)](https://www.npmjs.com/package/alltrails-mcp)\n[![license](https://img.shields.io/npm/l/alltrails-mcp)](LICENSE)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to [AllTrails](https://www.alltrails.com), giving you natural-language access to trail search, trail details, reviews, photos, weather, and your own saved lists and hiking history.\n\n> [!WARNING]\n> **AI-developed project.** This codebase was entirely built and is actively maintained by [Claude](https://www.anthropic.com/claude). No human has audited the implementation. Review all code and tool permissions before use.\n\n> [!CAUTION]\n> **Unofficial and unsupported.** AllTrails has **no public API**. This server reverse-engineers the internal API used by alltrails.com. That API is fronted by [DataDome](https://datadome.co) bot protection and governed by AllTrails' Terms of Service. It may break without notice, and automated access may violate their ToS — a prior third-party AllTrails project was disabled at AllTrails' request. Use this only for your own account, at your own discretion.\n\n## What you can do\n\nAsk Claude things like:\n\n- *\"Find waterfall trails near Portland, Oregon\"*\n- *\"What's the AllTrails rating and length of trail 10236086?\"*\n- *\"Summarize the recent reviews for this trail\"*\n- *\"What trails have I marked completed?\"*\n- *\"Show me the trails on my saved 'weekend hikes' list\"*\n\n## Requirements\n\n- [Claude Desktop](https://claude.ai/download) (or any MCP host)\n- [Node.js](https://nodejs.org) 22.5 or later\n- The [fetchproxy Transporter](https://github.com/chrischall/fetchproxy) browser extension and a signed-in alltrails.com tab (see [Authentication](#authentication))\n\n## Acknowledgement of Terms\n\nBy using this MCP server, you acknowledge and agree to the following:\n\n**1. This server accesses AllTrails using your own signed-in session.** It reuses the cookies from your own browser session; it cannot access anyone else's account or private data.\n\n**2. [AllTrails' Terms of Service](https://www.alltrails.com/terms) govern your use of this server**, just as they govern your direct use of AllTrails. AllTrails restricts automated access and scraping, and fronts its API with bot protection. Automated use through this server may breach those terms. You are agreeing to AllTrails' terms every time you invoke a tool.\n\n**3. Personal use only.** This project is not affiliated with, endorsed by, or sponsored by AllTrails, LLC. It is a personal automation tool. Do not use it to bulk-extract AllTrails' data, to build a competing product, or in any way that burdens their service.\n\n**4. You accept full responsibility** for any consequences — technical (rate-limiting, CAPTCHA challenges, account action) or otherwise. The maintainer provides no warranty and no support.\n\nThis section is the maintainer's good-faith summary — it is not legal advice and does not modify or supersede AllTrails' actual ToS.\n\n## Installation\n\n### 1. Clone and build\n\n```bash\ngit clone https://github.com/chrischall/alltrails-mcp.git\ncd alltrails-mcp\nnpm install\nnpm run build\n```\n\n### 2. Add to Claude Desktop\n\nEdit your Claude Desktop config file:\n\n- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd the `alltrails` entry inside `\"mcpServers\"` (create the key if it doesn't exist):\n\n```json\n{\n  \"mcpServers\": {\n    \"alltrails\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/alltrails-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/alltrails-mcp` with the path where you cloned the repo.\n\n### 3. Restart Claude Desktop\n\nQuit completely (Cmd+Q on Mac, not just close the window) and relaunch.\n\n### 4. Verify\n\nAsk Claude: *\"Search AllTrails for trails near me.\"*\n\n## Authentication\n\nAllTrails fronts its internal API with DataDome bot protection, and DataDome fingerprints the HTTP client itself — a cookie copied out of the browser and replayed from Node gets rejected even while the browser sails through. So the [fetchproxy](https://github.com/chrischall/fetchproxy) bridge is **required**: every API request runs as a same-origin fetch inside your own signed-in alltrails.com tab, reusing your authenticated session. There is no stored-cookie mode.\n\nRequirements: the fetchproxy Transporter extension installed, a signed-in alltrails.com tab open, and a one-time pair-code approval on first use (the trust persists).\n\nThe `x-at-key` app key AllTrails' own client sends is **never stored in this repo or your config** — the server captures the live value from your tab's own API traffic on first need, keeps it in memory only, and re-captures automatically if AllTrails rotates it. The `alltrails_healthcheck` tool round-trips a probe through the bridge and tells you which hop broke.\n\n### Configuration\n\n| Env var | Required | Purpose |\n|---------|----------|---------|\n| `ALLTRAILS_USER_ID` | No | Numeric user id for the per-user tools; defaults to the signed-in user via `/api/alltrails/me`. |\n| `ALLTRAILS_WS_PORT` | No | fetchproxy concentrator port (default `37149`, shared by the whole fetchproxy fleet — override only for local dev/tests). |\n| `ALLTRAILS_LOCALE` / `ALLTRAILS_CALLER` | No | Override the corresponding request headers. |\n| `ALLTRAILS_REQUEST_TIMEOUT_MS` | No | Per-request timeout in ms (default `30000`), applied on both paths. |\n| `ALLTRAILS_DEBUG_LOG` | No | `1`/`true`/`yes`/`on` logs every request/response to stderr (Cookie redacted). |\n\n## Available tools\n\nAll tools are **read-only** — this server never writes to AllTrails.\n\n| Tool | What it does |\n|------|-------------|\n| `alltrails_search` | Search AllTrails by trail or place name — free-text queries use the same suggestions endpoint as the alltrails.com search box (`types: [\"trail\"]` narrows to trails only) |\n| `alltrails_resolve_location` | Resolve a place name to AllTrails location records (country/state/city/area/POI) with each one's kind, coordinates, slug, and disambiguation label |\n| `alltrails_get_trail` | Trail details — name, overview, length, elevation gain, difficulty, rating, route type, location (`detail`: `basic`/`medium`/`offline` picks what AllTrails sends us) |\n| `alltrails_get_trail_reviews` | User reviews for a trail — `{user, rating, comment}` each |\n| `alltrails_get_trail_photos` | Photos for a trail — slim records with a fetchable image `url` |\n| `alltrails_get_trail_gpx` | Export a trail's route as GPX 1.1 (track points + elevation) |\n| `alltrails_get_trail_weather` | Weather overview for a trail |\n| `alltrails_get_profile` | The signed-in user's profile |\n| `alltrails_list_user_lists` | A user's saved lists / favorites |\n| `alltrails_get_list_items` | The trails saved in a list, by list id — ordered `{trailId, type, order, notes, addedAt}`, hydrate each via `get_trail` |\n| `alltrails_list_completed_trails` | A user's completed trails |\n| `alltrails_get_activity_feed` | A user's activity feed (`feed`: `local`/`timeline`/`personal` for the items, omit for the directory; `cursor` paginates) |\n| `alltrails_healthcheck` | Round-trips a probe through the fetchproxy bridge and reports role/port/timing plus a plain-English hint about which hop broke |\n\nThe per-user tools default to the signed-in user (resolved via `/api/alltrails/me` or `ALLTRAILS_USER_ID`); pass `userId` to target a public profile.\n\n### Response shape: `view`\n\n`alltrails_search`, `alltrails_get_trail`, `alltrails_get_trail_reviews`,\n`alltrails_get_trail_photos`, `alltrails_get_list_items` and\n`alltrails_get_activity_feed` take a `view` parameter with two rungs:\n\n| `view` | What you get |\n|--------|--------------|\n| `compact` | **The default.** The slim projection described in the table above — the fields a caller acts on. Nothing to pass. |\n| `full` | AllTrails' whole untouched record. |\n\nCompact is the default deliberately. These projections existed before, behind\n`compact: false` and a tool description asking the caller to please opt in — and\nan efficiency that has to be requested is one that usually is not. Ask for\n`view: \"full\"` when you need a field the projection drops; the commonest is\nroute geometry from `alltrails_get_trail`.\n\n> **`view` is not `detail`.** `alltrails_get_trail` also takes `detail`\n> (`basic`/`medium`/`offline`), and that one is a **passthrough to AllTrails** —\n> it decides what the API sends *us*. `view` decides what this server hands\n> *you*. Route geometry needs both: `detail: \"offline\"` to fetch it and\n> `view: \"full\"` to keep it. The collision is exactly why the fleet parameter is\n> named `view`.\n>\n> One projection is not a subset: `alltrails_get_trail_photos`' `url` is\n> **derived** by the compact rung (AllTrails' record carries no image URL), so\n> `view: \"full\"` does not contain it.\n\n## Troubleshooting\n\n**403 Forbidden** — AllTrails' DataDome protection rejected the request. This usually means the tab isn't signed in (or DataDome is challenging it) — sign into alltrails.com in an open tab and retry.\n\n**\"AllTrails bridge: …\"** — the bridge itself failed before reaching AllTrails (extension not running, pairing not approved, no tab). Run `alltrails_healthcheck` for a diagnosis, and check the Transporter extension popup.\n\n**\"AllTrails: capturing the x-at-key app key failed…\"** — the key capture only sees requests your tab itself makes, and an idle tab makes none. Open or refresh a signed-in www.alltrails.com page and retry.\n\n**Empty / unexpected results** — the internal AllTrails endpoints are undocumented and change over time; responses may shift. Enable `ALLTRAILS_DEBUG_LOG=1` to inspect the raw traffic on stderr.\n\n## Development\n\n```bash\nnpm test         # run the vitest suite\nnpm run build    # tsc → dist/, then esbuild bundle → dist/bundle.js\nnpm run dev      # node --env-file=.env dist/index.js (requires built dist)\n```\n\n`vitest.config.ts` enforces 100% coverage on `src/**` (except the stdio entry point). Main is protected — all changes land via PR. See `CLAUDE.md` for the full PR + release flow.\n\n### Project structure\n\n```\nsrc/\n  index.ts          MCP server entry (runMcp + StdioServerTransport)\n  protocol.ts       Wire-level constants (BASE_URL, app key, headers)\n  transport.ts      createAllTrailsTransport(): the fetchproxy bridge transport\n  client.ts         AllTrailsClient — bridge requests, live x-at-key capture, 429 retry\n  config.ts         Env parsing (api key, headers, timeout, port, user id, debug)\n  validate.ts       parseAllTrails(): zod validation of responses at call sites\n  tools/\n    _shared.ts      Response helpers + resolveUserId\n    trails.ts       get_trail, reviews, photos, weather, gpx export\n    explore.ts      search, list by state/country\n    user.ts         profile, saved lists, completed trails, activity feed\n    healthcheck.ts  alltrails_healthcheck (bridge diagnostics)\ntests/              Mirrors src/; mocks AllTrailsClient.request via vi.spyOn\n```\n\n### Request flow\n\nEvery API request runs as a same-origin fetch inside your signed-in alltrails.com tab, via the fetchproxy bridge (`src/transport.ts`, the shared `createFetchproxyTransport` factory). The browser carries its own cookies; the server attaches only the AllTrails protocol headers (`x-at-key` etc.), which an in-tab fetch doesn't add on its own. There is no Node-direct mode — DataDome fingerprints the HTTP client, so only in-tab requests are reliable.\n\nAlso see the [fetchproxy README](https://github.com/chrischall/fetchproxy) for extension install instructions.\n\n## License\n\nMIT\n",
  "bytes": 11749,
  "sha": "d3716564b21dc7e88dfbe42c9d0b78812aa8d60b1f26b63c6d6e2168ed323a61",
  "repo_slug": "chrischall/alltrails-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_chrischall_alltrails_mcp_2cd31425/readme"
}