exercise-mcp

MCP server over hasaneyldrm/exercises-dataset — 1,324 exercises, 10 languages, animation GIFs.

Tools: list_facets, search_exercises, get_exercise, build_workout.

lib/server.js     data loading + tool definitions (shared)
server.js         stdio (default) / --http express entrypoint
api/mcp.js        Vercel serverless entrypoint
scripts/trim-data.js  drop unused languages: 17 MB -> 1.7 MB

Setup

npm install
npm run build            # downloads + trims the dataset into data/

node server.js            # stdio; prints "exercise-mcp ready (1324 exercises)"

Point EXERCISES_JSON=data/exercises.min.json at the trimmed file for any deployed environment.

Local (Claude Desktop / Claude Code)

claude mcp add exercise-db -- node /absolute/path/to/exercise-mcp/server.js

Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "exercise-db": { "command": "node", "args": ["/abs/path/server.js"] } } }

Local servers do not reach claude.ai or the mobile apps.

Railway (recommended)

Commit data/exercises.min.json, push, then railway up. railway.json sets the start command and /health check; the server binds 0.0.0.0:$PORT.

Set MCP_TOKEN in the Railway variables to require Authorization: Bearer <token> on /mcp.

Connector URL: https://<project>.up.railway.app/mcp

Vercel

Works, with caveats — see vercel.json. Deploy the repo as-is; the function lives at /api/mcp and includeFiles ships the trimmed dataset into the bundle.

• The dataset parses on cold start (~1.5 s for the full file, ~80 ms trimmed), then stays in module scope while the instance is warm. Trim before deploying.
• Stateless only: GET/DELETE return 405, which is correct for the stateless Streamable HTTP profile the SDK serves with sessionIdGenerator: undefined.
• Do not put the endpoint behind Vercel's edge cache; MCP responses are per-request.

Connector URL: https://<project>.vercel.app/api/mcp

Adding it to Claude

Settings → Connectors → Add custom connector → paste the URL. Claude reaches your server from Anthropic's cloud, so it must be publicly resolvable — localhost and private networks won't work.

Notes

• Search returns 5-field rows and get_exercise returns one language, because raw records are ~13 KB each and would flood the model's context.
• image / gif_url are repo-relative; the server rewrites them to absolute raw.githubusercontent.com URLs. Override with MEDIA_BASE if self-hosting media.
• Licence: metadata and instruction text MIT; GIFs and thumbnails are © Gym visual, redistributed with permission. Keep the attribution, and get your own media licence before shipping a product.