trails-mcp

trails-mcp

A multi-service MCP server for outdoor / mapping data. Service 1 wraps the openWaymarked Trails API (recreational routes from OpenStreetMap)and adds OpenStreetMap Nominatim geocoding so trails canbe found by place name. Service 2 adds Windy pointforecasts for trail weather, marine, and air-quality planning.

Trail search is read-only and needs no API keys. Windy forecasts require aPoint Forecast API key (WINDY_API_KEY).

What the AI can do

• Search trails by name or reference code (GR20, E5, "Pennine Way")
• Find trails near a place name in one step ("hiking trails near Zermatt")
• Find trails inside a lon/lat bounding box
• Get full route details: length, operator, description, website, Wikipedia, OSM tags, bbox,sub/super-routes, and (optionally) the full path geometry
• Get a route's elevation profile
• Get route geometry clipped to a map box (GeoJSON)
• Resolve a route's Wikipedia link
• Get a guidepost (signpost node)
• Get a route's waymarking symbol (SVG shield)
• Geocode any place name to coordinates
• Get weather/marine/air-quality forecasts at any lat/lon (Windy Point Forecast API)
• Browse all Windy models, parameters, and pressure levels with descriptions

All six Waymarked Trails flavours are supported via a flavour parameter on each tool:hiking (default), cycling, mtb, riding, skating, slopes.

Coordinates: the upstream API speaks Web Mercator (EPSG:3857) internally. This serveraccepts and returns WGS84 lon/lat everywhere — the conversion is automatic. Routegeometry is summarised by default (geometry_detail: "summary") to keep responses small;pass "full" for every coordinate or "none" to omit geometry.

Tools

Install & build

npm install
npm run build      # compiles src/ -> dist/
npm test           # unit tests for the geo/conversion helpers

Requires Node >= 18.18 (developed on Node 22).

Connect to an MCP client

The same stdio command works everywhere; only the config file differs. Run npm run buildfirst — the config points at dist/index.js.

Claude Code

Either run:

claude mcp add trails -- node /Users/chiragahuja/Desktop/trails-mcp/dist/index.js

…or add to ~/.claude.json (global) or a project .mcp.json:

{
  "mcpServers": {
    "trails": {
      "command": "node",
      "args": ["/Users/chiragahuja/Desktop/trails-mcp/dist/index.js"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (project-scoped):

{
  "mcpServers": {
    "trails": {
      "command": "node",
      "args": ["/Users/chiragahuja/Desktop/trails-mcp/dist/index.js"]
    }
  }
}

Live-development (no build step)

Point the client at the TypeScript source via tsx instead of the built file:

{
  "mcpServers": {
    "trails": {
      "command": "npx",
      "args": ["tsx", "/Users/chiragahuja/Desktop/trails-mcp/src/index.ts"]
    }
  }
}

Try it

Use the MCP Inspector:

npm run inspect

Or, in a connected client, prompt:

Find hiking trails near Zermatt and show details of the longest one.

…which chains find_routes_near_place → get_route_details.

Configuration (env vars)

Copy .env.example to .env.dev and set your Windy Point Forecast key (create one atapi.windy.com). For local dev, npm run dev loads.env.dev automatically. For MCP clients, pass env vars in the server config:

{
  "mcpServers": {
    "trails": {
      "command": "node",
      "args": ["/path/to/trails-mcp/dist/index.js"],
      "env": { "WINDY_API_KEY": "your_point_forecast_key" }
    }
  }
}

Architecture

src/
  core/        registry, tool type, http, errors, rate limiter, logger, result helpers
  geo/         Mercator <-> lon/lat conversion, bbox helpers, geometry trimming
  services/
    index.ts   registerAllServices() — the single place new services plug in
    geocoding/ Nominatim client + geocode_place (shared, rate-limited)
    waymarked/ Waymarked Trails client, response shapers, and one file per tool
    windy/     Windy Point Forecast client, parameter catalog, forecast shaping

Adding another service = create src/services/<name>/ with a register() function and addone call in src/services/index.ts. No existing tool files change. Tool names are namespacedto avoid collisions, and the registry rejects duplicates.

Attribution & usage

• Trail data: © OpenStreetMap contributors, served by Waymarked Trails (Sarah Hoffmann), ODbL.
• Geocoding: OpenStreetMap Nominatim — used within itsusage policy (max 1 request/sec,descriptive User-Agent), enforced in-process.

Please be considerate with request volume; these are free community services.

License

MIT (this wrapper). Upstream data/services keep their own licenses.