running.services MCP server
Commit Nov 15, 2026Lets an AI client search for US running races, routes, and community resources using location, distance, and date filters.
Also known as biserd/Running-Directory, running-directory
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 15, 2026
- License
- —
What is running.services MCP?
running.services lets an AI client search for US running races, routes, and community resources using location, distance, and date filters.
Summary generated from the project's README
About running.services MCP server
Finding specific running events and training paths across the United States is what this MCP server enables for athletes and developers. It provides access to a massive dataset containing over 17,150 races pulled from the RunSignUp API, along with 50 curated running routes that include elevation data and difficulty ratings. Users can filter through this information using specific criteria such as state, city, distance, surface type, or date.
This server functions as a data hub that connects AI clients to a structured PostgreSQL database. It offers specialized endpoints to discover popular or trending races, find routes near specific coordinates, and explore community resources like running influencers, podcasts, and books. Developers can also access curated collections, such as lists of the best marathons or Boston Qualifying races, to provide highly specific recommendations to end users.
What you can do with it
- 1Discover local running eventsFind upcoming races in a specific city filtered by distance and surface type.
- 2Plan outdoor training routesSearch for running routes that include elevation data and difficulty ratings.
- 3Explore running community mediaIdentify running podcasts and books to supplement a training schedule.
- 4Locate races by proximityIdentify running events located near specific geographic coordinates.
Written from the project's README. Every use case is checked against a quote from it.
How to install running.services MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall running.services MCP in Claude Code
$ claude mcp add --transport http running-directory https://running.services/mcpInstall running.services MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"running-directory": {
"url": "https://running.services/mcp"
}
}
}Install running.services MCP in VS Code
.vscode/mcp.json
{
"servers": {
"running-directory": {
"type": "http",
"url": "https://running.services/mcp"
}
}
}Install running.services MCP in VS Code CLI
$ code --add-mcp '{"name":"running-directory","type":"http","url":"https://running.services/mcp"}'Install running.services MCP in Codex
$ codex mcp add running-directory --url https://running.services/mcpInstall running.services MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.running-directory] url = "https://running.services/mcp"
Install running.services MCP in Gemini CLI
$ gemini mcp add -s user --transport http running-directory https://running.services/mcpInstall running.services MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"running-directory": {
"url": "https://running.services/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebiserd/running-directory is public and reachablegithub.com/biserd/running-directory ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-14github.com/biserd/running-directory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 311 msPass
README
View on GitHubrunning.services
A data-driven running hub for the USA — a comprehensive race calendar, route directory, and running community platform built for programmatic SEO at scale.
Live: running.services
What It Does
running.services aggregates running data across all 50 US states into a single platform with thousands of SEO-optimized pages:
- Race Calendar — 17,150+ real races ingested from the RunSignUp API, filterable by state, city, distance, surface, and date
- Route Directory — 50 curated running routes with interactive maps, difficulty ratings, elevation data, and plotted route paths
- Unified State & City Hubs — Location-specific pages consolidating all races, routes, stats, and explore links for every state and city
- Running Community — Curated directories of running influencers, podcasts, and books
- Collections — "Best of" pages like Best Marathons, Boston Qualifying Races, and Best Trail Routes
- Tools Integration — Links to AITracker.run for AI-powered race prediction, pace calculation, and training plans
Architecture
Monorepo Structure
client/ React frontend (Vite + TypeScript)
server/ Express backend (TypeScript)
shared/ Shared schema and types
script/ Build scripts
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript, Vite |
| Routing | Wouter v3 (SSR-compatible) |
| State Management | TanStack React Query v5 |
| UI Components | shadcn/ui + Radix UI + Tailwind CSS v4 |
| Backend | Express 5, Node.js, TypeScript |
| Database | PostgreSQL + Drizzle ORM |
| Maps | Leaflet + OpenStreetMap (route detail pages), SVG + OSM tiles (route cards) |
| Build | Vite (client + SSR), esbuild (server) |
Server-Side Rendering (SSR)
Every page is fully server-rendered for SEO crawlers:
- Data Prefetching —
server/ssr-prefetch.tsmaps ~25 URL patterns to data prefetch functions, populating the React Query cache server-side - Hydration — Uses
dehydrate/HydrationBoundaryso the client doesn't re-fetch data already rendered on the server - ISR-like Caching — In-memory TTL cache (5-min default, 500-entry max) with stale-while-revalidate semantics
- Graceful Fallback — If SSR fails, falls back to client-side rendering with dynamic meta tags still injected
SEO Infrastructure
- Canonical URLs — Every page has a
<link rel="canonical">tag with absolute URLs - Dynamic Meta Tags — Per-page title, description, Open Graph, and Twitter Card tags
- JSON-LD Structured Data — WebSite, CollectionPage, SportsEvent, and Place schemas
- Sitemaps — Auto-generated split sitemaps for races, routes, states, cities, collections, influencers, podcasts, and books
- robots.txt — Proper crawler directives with sitemap references
URL Structure
The site is designed for programmatic SEO, generating thousands of pages from structured data:
Races
| URL | Description |
|---|---|
/races/ |
Main race hub with filters and discovery |
/races/usa/ |
All 50 states directory |
/races/state/{state}/ |
State-specific race calendar |
/races/state/{state}/city/{city}/ |
City race listings |
/races/year/{yyyy}/ |
Year view with month navigation |
/races/year/{yyyy}/month/{mm}/ |
Month race listings |
/races/{slug}/ |
Individual race detail page |
/races/nearby/ |
Geolocation-based race discovery |
Routes
| URL | Description |
|---|---|
/routes/ |
Main routes hub |
/routes/state/{state}/ |
State routes directory |
/routes/state/{state}/city/{city}/ |
City routes |
/routes/{slug}/ |
Route detail page with interactive map |
Unified Location Hubs
| URL | Description |
|---|---|
/state/{state}/ |
Unified state hub (races + routes + cities + stats) |
/state/{state}/city/{city}/ |
Unified city hub (races + routes + cross-links) |
Content
| URL | Description |
|---|---|
/collections/ |
Curated "best of" lists |
/influencers/ |
Running influencer directory |
/podcasts/ |
Running podcast directory |
/books/ |
Running book recommendations |
/tools/ |
AI-powered running tools |
/guides/ |
Running guides |
API
RESTful JSON API under the /api/ prefix:
GET /api/states List all states
GET /api/states/:slug Get a single state
GET /api/states/:stateSlug/cities List cities for a state
GET /api/cities/:stateSlug/:citySlug Get a city with state data
GET /api/races List races (filterable by state, distance, surface, city, year, month)
GET /api/races/:slug Get a single race
GET /api/races/popular Popular races
GET /api/races/trending Trending races
GET /api/races/nearby Races near coordinates
GET /api/race-occurrences List race occurrences
GET /api/routes List routes (filterable by state, surface, type, city)
GET /api/routes/:slug Get a single route
GET /api/collections List collections
GET /api/collections/:slug Get a single collection
GET /api/influencers List influencers
GET /api/influencers/:slug Get a single influencer
GET /api/podcasts List podcasts
GET /api/podcasts/:slug Get a single podcast
GET /api/books List books
GET /api/books/:slug Get a single book
Admin Endpoints (protected by X-ADMIN-KEY header)
POST /api/admin/ingest/races Full race ingestion from RunSignUp
POST /api/admin/ingest/races/state/:st Single-state race ingestion
GET /api/admin/stats Database statistics
Database Schema
PostgreSQL with Drizzle ORM. Key tables:
| Table | Purpose |
|---|---|
states |
50 US states with race/route counts and popular cities |
cities |
Cities with lat/lng, linked to states |
races |
17,150+ races with distance, surface, elevation, coordinates, quality scores |
race_occurrences |
Individual race event instances with dates, pricing, status |
routes |
Running routes with polyline paths, difficulty, surface, elevation data |
sources |
Data source registry (RunSignUp, manual, etc.) |
source_records |
Raw ingested records for deduplication |
collections |
Curated "best of" groupings |
influencers |
Running influencer profiles |
podcasts |
Running podcast directory |
books |
Running book recommendations |
Data Ingestion
The server/ingestion/ pipeline handles importing races from the RunSignUp API:
- Fetching — Paginated API calls per state with date range and modified-since support
- Normalization — Name cleaning, location key generation, URL normalization
- Deduplication — Exact match (name + location + date) and fuzzy match (trigram similarity > 0.6)
- Quality Scoring — 0-100 score based on field completeness (description, website, registration URL, etc.)
- Upsert — Creates or updates races, marks stale races inactive after 45 days
Route Maps
Route detail pages feature interactive Leaflet maps with OpenStreetMap tiles showing the plotted route path. Route cards across the site display static map previews using OSM tile images with SVG-rendered route overlays.
Route paths are generated based on:
- Loop routes — Circular paths with natural-looking variation
- Out-and-Back routes — Linear paths with a parallel return
- Point-to-Point routes — Winding paths from start to finish
Development
npm install # Install dependencies
npm run dev # Start dev server with HMR and SSR
npm run db:push # Sync database schema
npm run build # Production build (client + SSR + server)
npm start # Run production server
Environment Variables
| Variable | Description |
|---|---|
DATABASE_URL |
PostgreSQL connection string |
ADMIN_API_KEY |
API key for admin endpoints |
PORT |
Server port (default: 5000) |
License
All rights reserved.
running.services MCP questions
How do I add running.services MCP to Claude Code?
Run claude mcp add --transport http running-directory https://running.services/mcp in your terminal. Add --scope user to make it available in every project.
How do I add running.services MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What kind of running data is available?
The platform provides a race calendar with over 17,000 races, a directory of 50 curated running routes with maps, and a community directory of influencers, podcasts, and books.
Can I filter races by specific criteria?
Yes, you can filter races by state, city, distance, surface, and date.
How are the running routes displayed?
Route detail pages include interactive Leaflet maps with OpenStreetMap tiles showing the plotted path.