komoot-mcp
Provides tools for interacting with Komoot's web API, allowing users to list planned and recorded tours by sport, location and radius, retrieve surface and way-type breakdowns (gravel, asphalt, dirt), download tours as GPX, upload GPX files as new planned tours, and find highlights near a point or among saved bookmarks. Also builds new gravel routes by extracting single-surface sections from several saved tours, scoring runs by gravel length and nearby highlights, and joining them with OSRM cycling connectors into a GPX track plus waypoint list for the Komoot planner.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@komoot-mcp Find a 50 km gravel loop near Amsterdam, at least 60% unpaved"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
komoot-mcp
An MCP server that lets Claude search your Komoot tours by distance, start point, surface and scenery, and build new gravel routes from the best sections of tours you already saved.
Preview
You: Find me a 50 km gravel loop within 30 minutes of Amsterdam,
at least 60% unpaved, and tell me what is scenic along the way.
Claude: I checked 14 planned tours near Amsterdam and pulled surface data for the
closest matches.
1. Vechtplassen gravel loop: 48 km, 71% gravel (compacted and dirt),
starts in Weesp (25 min drive). Passes 3 saved highlights:
Ankeveense Plassen, Fort Uitermeer, Naardermeer boardwalk.
2. Diemerbos and IJmeer dike: 52 km, 63% gravel, starts at Diemen.
Exposed dike section for 9 km, watch the wind.
3. Spaarnwoude polders: 55 km, 58% gravel, just under your target.
Want the GPX for route 1, or should I build a new loop that combines
the gravel sections of all three?Related MCP server: komoot-mcp
What it does
%%{init: {"flowchart": {"wrappingWidth": 600, "nodeSpacing": 30, "rankSpacing": 32}}}%%
flowchart TB
Q(["You, in Claude: a distance, a start, how much gravel, what to see"]):::human
Q --> CL["`**Claude** picks the tools and calls them over MCP`"]:::sys
CL --> T1["list_tours: planned and recorded, by sport, place, radius"]:::sys
T1 --> T2["get_tour_segments: surface and way-type spans turned into percentages"]:::sys
T2 --> T3["get_highlights and your saved ones, near a point"]:::sys
T3 --> RC["build_combined_route: single-surface segments, forward runs, scored by gravel and highlights"]:::sys
RC --> OS["OSRM public cycling router joins the chosen runs"]:::sys
OS --> OUT["A GPX track plus a waypoint list for the Komoot planner"]:::out
OUT --> R(["You ride it, or upload it as a new planned tour"]):::human
classDef sys fill:#1f3a5f,stroke:#7aa2d8,color:#ffffff
classDef human fill:#6b4514,stroke:#e0a95a,color:#ffffff
classDef out fill:#1e4d3a,stroke:#6fcf97,color:#ffffffLists your planned and recorded tours by sport, location and radius.
Returns a tour's surface breakdown (gravel, asphalt, dirt) and way types, so a ride can be scored by how much is unpaved.
Downloads any tour as GPX, or uploads a GPX as a new planned tour.
Finds highlights near a point, and reads the ones you bookmarked.
Builds a new route from the gravel sections of several saved tours, joined by short OSRM cycling connectors, as a GPX track plus a waypoint list for the Komoot planner.
Constraints: credentials live in the system keychain or in environment variables, never on disk in this project. Tests run without network.
Why this exists
I ride gravel around Amsterdam and wanted to plan rides from inside Claude instead of clicking through maps. Komoot has the surface data; this server makes it available as tools, and gravel-ride-plan uses them for the route step of a full ride plan. It is the same habit as the work tools on my profile: when a routine has a data source, give the assistant the tools and let it do the lookups.
Requirements
Python 3.10 or newer and uv
A Komoot account. Credentials go in environment variables or the system keychain (see Install); they are never written to disk by this project.
Claude Code or Claude Desktop
Unofficial: this server talks to Komoot's web API and is not affiliated with or endorsed by Komoot; use it within Komoot's terms, at your own risk. The route combiner calls the public OSRM demo server, at most 30 calls per build, within its light-use policy.
Install
git clone https://github.com/nunomnferreirapt/komoot-mcp.git
cd komoot-mcp
uv sync
uv run pytestRegister the server, then ask Claude once to run the setup_credentials tool: it stores your Komoot email and password in the system keychain under the service komoot-mcp, and no config file ever holds them. The password passes through the conversation that one time; set the two environment variables instead if you would rather it never did. Claude Code:
claude mcp add -s user komoot-mcp -- uv --directory /absolute/path/to/komoot-mcp run komoot-mcpClaude Desktop, in claude_desktop_config.json:
{
"mcpServers": {
"komoot-mcp": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/komoot-mcp", "run", "komoot-mcp"]
}
}
}If you prefer environment variables, set KOMOOT_EMAIL and KOMOOT_PASSWORD in the server's env block instead; they take precedence over the keychain. That block sits in plain text in the client's config file (claude_desktop_config.json, or ~/.claude.json for Claude Code), so the keychain is the safer place; to keep the password out of the config, export the two variables in the shell that starts the client.
Optional variables: KOMOOT_MCP_ROUTES_DIR (where built routes are saved, default ~/komoot-mcp-routes) and KOMOOT_MCP_CACHE_DIR (parsed tour cache, default ~/.cache/komoot-mcp). Both hold your tours' full GPS tracks and your saved highlights in plain files, so keep them outside any folder you push to a public repo.
Usage
Ask in plain language: "list my planned tours near Utrecht", "how much of tour 123456 is gravel", "build a 60 km gravel loop from Weesp using my saved tours". The tools are list_tours, get_tour_details, get_tour_segments, download_tour_gpx, upload_gpx_to_komoot, get_highlights, get_saved_highlights, build_combined_route and setup_credentials. To run the server by hand: uv run komoot-mcp (it speaks MCP over stdio).
How the route combiner works
A FastMCP app over Komoot's web API. It signs in with Basic Auth, keeps the short-lived session token in memory and retries once on a 401. Tour responses carry surface and way-type spans indexed into the coordinate array; the client turns these into percentages. The route combiner splits each tour into single-surface segments, groups them into runs that move forward along the start-to-end corridor, scores runs by gravel length and nearby saved highlights, and joins the chosen runs with OSRM's public cycling router. Parsed segments are cached on disk, so a rebuild only fetches tours it has not seen.
Repository layout
src/komoot_mcp/
__main__.py MCP tools and server entry point
auth.py credentials and Basic Auth session
client.py Komoot API calls and surface parsing
route_combiner.py segment splitting, run selection, OSRM connectors, GPX output
cache.py disk cache for parsed segments and highlights
tests/ pytest, no network
pyproject.toml uv project, console script komoot-mcpLicense
MIT, see LICENSE.
Built by Nuno Ferreira.
Available Tools
9 toolsbuild_combined_routeA
Build a custom gravel route by combining the best segments from multiple saved tours.
Selects gravel segments from saved tours within a corridor between start and end, ordered by forward progress. Connects them via OSRM cycling router. Every km follows either a saved-tour path or a short OSRM connector.
For loops: omit end_lat/end_lon. For point-to-point: provide both.
Uses a disk cache for parsed segments: only fetches new tours from the API. Set force_refresh=True to re-fetch all tour data.
Args: tour_ids: List of Komoot tour IDs to extract segments from. start_lat: Starting point latitude. start_lon: Starting point longitude. distance_km: Target route distance in km (default 50). min_gravel_pct: Minimum gravel percentage target (default 60). route_name: Name for the combined route. save_path: File path to save GPX. Defaults to $KOMOOT_MCP_ROUTES_DIR/.gpx (or ~/komoot-mcp-routes/ when the variable is not set). use_saved_highlights: If True, fetch saved highlights and use as waypoint attractors (default True). force_refresh: If True, ignore cache and re-fetch all tour data from Komoot API (default False). end_lat: End point latitude (for point-to-point routes). Omit for loops. end_lon: End point longitude (for point-to-point routes). Omit for loops.
Inputs: tour_ids (required), start_lat (required), start_lon (required), end_lat, +7 more. Returns: result
download_tour_gpxA
Download a Komoot tour as GPX file.
Args: tour_id: The Komoot tour ID. save_path: Optional file path to save the GPX. If empty, returns GPX XML as text.
Inputs: tour_id (required), save_path. Returns: result
get_highlightsB
Get highlights and points of interest near a location.
Highlights include scenic viewpoints, interesting places, and user-recommended spots that are useful for planning attractive gravel routes.
Args: lat: Latitude of the center point. lon: Longitude of the center point. radius_m: Search radius in meters (default 5000).
Inputs: lat (required), lon (required), radius_m. Returns: result
get_saved_highlightsA
Get your saved/bookmarked Komoot highlights.
Returns your personally saved highlights (scenic spots, viewpoints, interesting places you've bookmarked). These are used as waypoint attractors when building combined routes: the route combiner prefers paths that pass near your saved highlights.
Inputs: no named parameters. Returns: result
get_tour_detailsA
Get full details of a Komoot tour including surface types and way types.
Returns surface breakdown (gravel, asphalt, dirt, etc.) and way types (path, cycleway, street, etc.) which are essential for gravel ride planning.
Args: tour_id: The Komoot tour ID. include_coordinates: If True, include full GPS coordinate array (can be 1000+ points). Defaults to False to keep responses compact for scoring/ranking.
Inputs: tour_id (required), include_coordinates. Returns: result
get_tour_segmentsA
Get raw segment data (coordinates + surfaces + way types) for a tour.
Unlike get_tour_details which aggregates surface data, this returns the raw segment arrays needed for route combination: splitting tours by surface type and recombining the best gravel segments.
Args: tour_id: The Komoot tour ID.
Inputs: tour_id (required). Returns: result
list_toursA
List your Komoot tours with optional filtering by sport type, location, and radius.
Use near_lat/near_lon to search tours near a geographic point.
Args: sport_type: Sport type filter. Empty string = all sports. Common: touringbicycle, mtb, mtb_easy, racebike, hike. tour_type: Tour type. 'tour_planned' for planned, 'tour_recorded' for recorded. limit: Max number of tours to return. near_lat: Filter by latitude (center point). near_lon: Filter by longitude (center point). radius_km: Search radius in km (used with near_lat/near_lon).
Inputs: limit, near_lat, near_lon, radius_km, +2 more. Returns: result
setup_credentialsA
Store Komoot credentials in the system keychain for future use.
Call this once before using any other Komoot tools, unless you set the KOMOOT_EMAIL and KOMOOT_PASSWORD environment variables instead. Credentials are verified first, then stored in the system keychain under service 'komoot-mcp'; a failed sign-in stores nothing.
Inputs: email (required), password (required). Returns: result
upload_gpx_to_komootB
Upload a GPX file to Komoot as a new planned tour.
Args: gpx_path: Path to the GPX file to upload. name: Name for the new tour on Komoot. sport: Sport type. Common: touringbicycle, mtb, racebike.
Inputs: name (required), gpx_path (required), sport. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a largely distinct purpose, and the descriptions clarify potential overlaps. The main possible confusion is between get_tour_details and get_tour_segments, but the text explicitly differentiates aggregated data from raw segment arrays. Highlight tools are also distinguished by location-based versus saved/bookmarked results.
All tool names follow a clear snake_case, verb-first action_object pattern (e.g., setup_credentials, list_tours, download_tour_gpx, build_combined_route). The convention is consistent across the entire set with no mixed casing or vague verb styles.
Nine tools is well-scoped for a Komoot integration focused on credential setup, tour browsing, GPX handling, highlights, and route building. Each tool serves a distinct step in these workflows, with no obviously redundant or missing count-level concerns.
The surface covers credentials, tour listing/details, raw segments, GPX download/upload, highlights, saved highlights, and combined route building, forming a coherent gravel-planning toolkit. Minor gaps exist around tour metadata update/delete and saving highlights, but core creation/read/export/route-building workflows are covered.
Related MCP Connectors
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
tri-train is a training platform for triathletes that syncs activities from Strava and Garmin and exposes them to Claude through a remote MCP server. Ask Claude how your last block went, why your run pace dropped, or whether you are fresh enough for Sunday's race, and it answers from your real data: activities with laps and grade-adjusted pace, weekly load and the performance management chart (CTL/ATL/TSB), sleep, HRV and resting heart rate, and your race calendar with predictions. Claude can also act: create and adjust planned workouts with structured intervals, push them to your Garmin watch, add races and write notes. Every change is journaled and can be undone. Read and write access are separate OAuth scopes, and the server enforces them on every call. Built and hosted in Switzerland by a triathlete; data stays on our own servers (Swiss revDSG / GDPR).
Turn Claude or ChatGPT into a cycling coach that plans your week, grades it, and adapts. Free beta.
Your own cycling data for your AI assistant: rides, power, climbs and routes. Read-only.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects Claude to your Strava account so you can query your activities, stats, routes, and segments using natural language.2724 npm1MIT
- FlicenseBqualityCmaintenanceEnables users to interact with Komoot for managing tours, planning routes, exporting GPX/FIT, and accessing highlights and user profile.181-
- FlicenseAqualityDmaintenanceConnects Claude to your Strava fitness data, enabling natural language queries about your training history such as activities, stats, and routes.8-
- AlicenseBqualityBmaintenanceEnables Claude to design reliable hiking routes on real trails, computing accurate distance and elevation gain, locating notable points, technical passages, regulated areas, bivouac and stage options, and weather, with automatic validation across roughly 35 rules. Routes can be exported as GPX (including one file per day), Obsidian notes, HTML maps, and printable roadbooks.231MIT