Heart Routes

secupunk/scenic-pathfinder-ai

This connects Claude to CityHeart's GPS route generation service, letting you create heart-shaped running routes across 200+ cities. You can query available cities, generate GPX files for specific locations and distances (3–15 km), and retrieve routes compatible with Garmin, Strava, Apple Watch, and other GPS devices. Reach for this when building fitness apps, gift services, or location-based experiences where you need algorithmically generated GPS art that follows real streets. The routes work well for Valentine's Day campaigns, marathon prep tools, or any app where users want shareable activity tracker art. It talks to their Supabase backend via streamable HTTP and returns standard GPX format data.

tools: 7
transport: HTTP
last updated: May 22, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://zhenwiaphfwetckfysod.supabase.co/functions/v1/mcp --name heart-routes

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http heart-routes https://zhenwiaphfwetckfysod.supabase.co/functions/v1/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 7 tools

Verified live against the running server on Nov 6, 2026.

find_heart_route_in_cityFind an existing heart-shaped running route in a given city. Returns up to 5 AI-validated routes matching the city (and optionally a target distance). Use this when a user mentions a city and wants a heart route — e.g. "find me a heart-shaped route in Paris" or "I want to run...3 params

Find an existing heart-shaped running route in a given city. Returns up to 5 AI-validated routes matching the city (and optionally a target distance). Use this when a user mentions a city and wants a heart route — e.g. "find me a heart-shaped route in Paris" or "I want to run...

Parameters* required

city*string

City name, e.g. "Paris", "Tokyo", "New York". Case-insensitive.

max_distance_kmnumber

Optional max route length in kilometres. Filter to routes ≤ this distance. Common: 5, 10, 15, 21 (half-marathon).

prefer_goldboolean

If true, return only the highest AI-quality "gold" tier routes (ai_score >= 80). Default true.default: true

get_route_detailsGet full details for a specific heart route by its slug. Use after find_heart_route_in_city when the user picks one. Returns: city, distance, image URL, share URL, dedication (if any), and the GPX download deep-link.1 params

Get full details for a specific heart route by its slug. Use after find_heart_route_in_city when the user picks one. Returns: city, distance, image URL, share URL, dedication (if any), and the GPX download deep-link.

Parameters* required

slug*string

Route slug, e.g. "paris-7-2-km-heart-for-marie".

list_supported_citiesList cities that have at least one heart route available. Use when the user asks "where can I run a heart?" or hasn't picked a city yet. Returns city names + route counts, sorted by inventory size.1 params

List cities that have at least one heart route available. Use when the user asks "where can I run a heart?" or hasn't picked a city yet. Returns city names + route counts, sorted by inventory size.

Parameters* required

limitnumber

Max number of cities to return. Default 25, max 100.default: 25

generate_heart_routeStart a new heart-shaped route for a given city. Returns existing AI-validated matches from inventory PLUS a deep-link to the live builder for an on-demand fresh generation with the user's exact dedication and cause. Use when the user explicitly wants a NEW heart, or when an e...5 params

Start a new heart-shaped route for a given city. Returns existing AI-validated matches from inventory PLUS a deep-link to the live builder for an on-demand fresh generation with the user's exact dedication and cause. Use when the user explicitly wants a NEW heart, or when an e...

Parameters* required

cause_urlstring

Optional JustGiving / GoFundMe / Leetchi URL to embed in the GPX metadata. CityHeart never touches the money — the link is for the runner's Strava description to surface to donors.

city*string

City name, e.g. "Paris", "Tokyo".

dedicationstring

Optional person/cause name to bake into the heart (appears in the GPX, on Garmin Connect, and as the Strava activity title prefix).

distance_kmnumber

Target route length in km (3–25). Default 7.default: 7

in_memoryboolean

If true, the dedication is framed as a memorial ("In memory of [name]"). Default false.

add_dedicationCompose a builder URL with a dedication pre-filled — the name shows on the runner's GPS watch and in the Strava activity title. Use after the user picks a route (find/generate) and decides who the heart is for. Pure URL builder, no server-side state.3 params

Compose a builder URL with a dedication pre-filled — the name shows on the runner's GPS watch and in the Strava activity title. Use after the user picks a route (find/generate) and decides who the heart is for. Pure URL builder, no server-side state.

Parameters* required

citystring

Optional city to also pre-fill in the builder (skips the "pick a city" step in the chat-to-product handoff).

in_memoryboolean

If true, framed as "In memory of [name]". Default false.

name*string

Dedication name (e.g. "Marie", "Dad", "Cancer Research UK").

add_causeCompose a builder URL with a fundraising link pre-filled — the URL is embedded into the GPX metadata (description, filename) so it surfaces in the runner's Strava activity after they sync. CityHeart never collects the donation; the runner's donors click straight through to Jus...2 params

Compose a builder URL with a fundraising link pre-filled — the URL is embedded into the GPX metadata (description, filename) so it surfaces in the runner's Strava activity after they sync. CityHeart never collects the donation; the runner's donors click straight through to Jus...

Parameters* required

citystring

Optional city to also pre-fill.

fundraising_url*string

Fully-qualified donation URL (https://www.justgiving.com/... / https://gofundme.com/... / https://leetchi.com/... / https://www.helloasso.com/...).

export_gpxReturn the GPX download / checkout URL for a specific public route. The download itself happens on cityheart.run after a one-time €9.90 payment (Stripe — CityHeart never charges through the chat). Use after the user has picked a final route (find / get_details) and confirms th...1 params

Return the GPX download / checkout URL for a specific public route. The download itself happens on cityheart.run after a one-time €9.90 payment (Stripe — CityHeart never charges through the chat). Use after the user has picked a final route (find / get_details) and confirms th...

Parameters* required

slug*string

Route slug, e.g. "paris-7-2-km-heart-for-marie".

Readme

Details

Repository: github.com/secupunk/scenic-pathfinder-ai
Website: cityheart.run/mcp
Transport: HTTP
Registry: MCP registry, active
Tools verified: Nov 6, 2026