exercisebank-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 TotalCoaching
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This licence covers the example code in this repository. The exercise
+library, its videos, stills and metadata are licensed separately:
+https://exercisebank.net/license

package/README.md

@@ -0,0 +1,69 @@
+# exercisebank-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the
+[ExerciseBank API](https://exercisebank.net): 1,492 studio-filmed exercises with a hand-checked
+classification and a ranked map of which exercises can replace which. It lets Claude, Cursor and other
+MCP clients search real exercises by muscle, equipment, movement pattern, difficulty and joints to
+avoid, so a plan is built from exercises that exist, with videos your app is licensed to show.
+
+Use it while you build on the API (your coding agent explores the catalogue and the vocabulary as it
+writes your integration) or to prototype a workout generator before writing any code.
+
+## Install
+
+Get a free sandbox key (no card) at https://exercisebank.net/signup, then:
+
+**Claude Code**
+
+```bash
+claude mcp add exercisebank --env EB_KEY=eb_live_… -- npx -y exercisebank-mcp
+```
+
+**Claude Desktop, Cursor, Windsurf and other clients** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+
+```json
+{
+  "mcpServers": {
+    "exercisebank": {
+      "command": "npx",
+      "args": ["-y", "exercisebank-mcp"],
+      "env": { "EB_KEY": "eb_live_…" }
+    }
+  }
+}
+```
+
+It runs on your machine over stdio; the key stays in your client's configuration. Node 18 or later.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_vocabulary` | The exact filter values: muscles, equipment, movement patterns, joints, impact; the catalogue version; the ids a sandbox key gets video for |
+| `search_exercises` | Search and filter: `q`, `muscle`, `equipment` (the gear the person has), `pattern`, `minDifficulty`, `maxDifficulty`, `excludeJoints`, `impact`, `unilateral`, `limit`, `offset` |
+| `get_exercise` | The full record: description, coaching cues, French, classification |
+| `get_substitutes` | Ranked replacements with a score and a reason each, filtered by gear and joints to avoid |
+| `get_media_urls` | Signed video and still URLs. Only when `EB_END_USER` is set (below) |
+
+### Video
+
+ExerciseBank signs media only for a named person, and that person counts as an end user on the plan.
+To get `get_media_urls`, add an opaque id for whoever is at this machine:
+
+```json
+"env": { "EB_KEY": "eb_live_…", "EB_END_USER": "dev-laptop-anna" }
+```
+
+URLs expire after 15 minutes. A sandbox key gets media for the 50-exercise sample listed by
+`get_vocabulary`; a paid plan gets all 1,492.
+
+## In your product
+
+This server is for the developer's desk. A product calls the API from its own backend, with its own
+users' ids: use the [`exercisebank`](https://www.npmjs.com/package/exercisebank) client and see the
+guide, [an AI workout generator with Claude](https://exercisebank.net/guides/ai-workout-generator).
+
+- API reference: https://exercisebank.net/docs · for language models: https://exercisebank.net/llms.txt
+- Pricing, by monthly end users: https://exercisebank.net/pricing
+
+MIT licensed. The library itself is licensed through a plan: https://exercisebank.net/license

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * MCP server for the ExerciseBank API (https://exercisebank.net), over stdio.
+ * EB_KEY       your key (free sandbox key: https://exercisebank.net/signup)
+ * EB_END_USER  optional: an opaque id for the person at this machine. Set it to get the get_media_urls tool;
+ *              media is only ever signed for a named person, and that person counts as an end user on the plan.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ExerciseBank, ExerciseBankError } from "exercisebank";
+import { z } from "zod";
+let eb;
+try {
+    eb = new ExerciseBank();
+}
+catch (e) {
+    console.error(`exercisebank-mcp: ${e.message}`);
+    process.exit(1);
+}
+const END_USER = process.env.EB_END_USER?.trim();
+const server = new McpServer({ name: "exercisebank", version: "0.1.0" });
+const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });
+const guard = (run) => async (args) => {
+    try {
+        return text(await run(args));
+    }
+    catch (e) {
+        const message = e instanceof ExerciseBankError ? `${e.message}${e.retryAfter ? ` (retry in ${e.retryAfter} s)` : ""}` : String(e);
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+};
+/** What a model needs to choose between exercises; get_exercise has the description and cues. */
+const brief = (e) => ({
+    id: e.id, name: e.name, ...(e.nameFr ? { nameFr: e.nameFr } : {}),
+    primaryMuscles: e.primaryMuscles, secondaryMuscles: e.secondaryMuscles, equipment: e.equipment,
+    movementPattern: e.movementPattern, difficulty: e.difficulty, loadedJoints: e.loadedJoints, impact: e.impact, unilateral: e.unilateral,
+});
+const names = (what) => z.array(z.string()).optional().describe(`${what}. Values from get_vocabulary.`);
+server.registerTool("get_vocabulary", {
+    title: "ExerciseBank vocabulary",
+    description: "The exact values the ExerciseBank filters accept: muscles, equipment, movement patterns, joints, impact. Call this once before search_exercises or get_substitutes. Also returns the catalogue version and the ids a sandbox key gets video for.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, guard(async () => {
+    const m = await eb.meta();
+    return { version: m.version, count: m.count, plan: m.plan, enums: m.enums, sandboxMediaSample: m.sample };
+}));
+server.registerTool("search_exercises", {
+    title: "Search ExerciseBank exercises",
+    description: "Search 1,492 studio-filmed exercises. Every filter is optional and they combine. Only exercises returned here exist: never invent an exercise or an id. Without q the order is alphabetical, so filter rather than page.",
+    inputSchema: {
+        q: z.string().optional().describe("Text in the name, French name or aliases, e.g. 'goblet squat'"),
+        muscle: names("Primary or secondary muscles"),
+        equipment: names("The gear the person HAS (bodyweight is always allowed); exercises needing anything else are left out"),
+        pattern: names("Movement patterns"),
+        minDifficulty: z.number().int().min(1).max(5).optional(),
+        maxDifficulty: z.number().int().min(1).max(5).optional().describe("1 beginner to 5 advanced"),
+        excludeJoints: names("Leave out anything that loads these joints, e.g. a sore knee"),
+        impact: z.array(z.enum(["low", "moderate", "high"])).optional(),
+        unilateral: z.boolean().optional(),
+        limit: z.number().int().min(1).max(100).optional().describe("Default 25"),
+        offset: z.number().int().min(0).optional(),
+    },
+    annotations: { readOnlyHint: true },
+}, guard(async (args) => {
+    const r = await eb.search(args);
+    return { total: r.total, next: r.next, exercises: r.data.map(brief) };
+}));
+server.registerTool("get_exercise", {
+    title: "Get one ExerciseBank exercise",
+    description: "The full record for one exercise id: description, coaching cues, French, classification, which media exists.",
+    inputSchema: { id: z.string().describe("An id from search_exercises, e.g. tc-2000") },
+    annotations: { readOnlyHint: true },
+}, guard(({ id }) => eb.get(id)));
+server.registerTool("get_substitutes", {
+    title: "Substitutes for an exercise",
+    description: "Ranked replacements for one exercise, each with a score and the reason it works as a swap. Filter by the gear the person has and by joints to avoid.",
+    inputSchema: {
+        id: z.string().describe("The exercise to replace"),
+        equipment: names("The gear the person has"),
+        excludeJoints: names("Leave out substitutes that load these joints"),
+        limit: z.number().int().min(1).max(50).optional().describe("Default 10"),
+    },
+    annotations: { readOnlyHint: true },
+}, guard(async ({ id, ...params }) => (await eb.substitutes(id, params)).map((s) => ({ score: s.score, reason: s.reason, exercise: brief(s.exercise) }))));
+if (END_USER)
+    server.registerTool("get_media_urls", {
+        title: "Signed video and still URLs",
+        description: "Short-lived signed URLs (video clip and still) for up to 50 exercise ids, issued for the person named in EB_END_USER. They expire, 15 minutes by default: show them now, store exercise ids. A sandbox key gets media only for the ids in get_vocabulary.sandboxMediaSample.",
+        inputSchema: {
+            ids: z.array(z.string()).min(1).max(50),
+            kinds: z.array(z.enum(["mp4", "still"])).optional().describe("Default both"),
+        },
+        annotations: { readOnlyHint: true },
+    }, guard(({ ids, kinds }) => eb.mediaUrls({ endUser: END_USER, ids, ...(kinds ? { kinds } : {}) })));
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "exercisebank-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the ExerciseBank API (exercisebank.net): search 1,492 filmed exercises by muscle, equipment, movement pattern, difficulty and joints to avoid; get substitutes with reasons.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "exercisebank",
+    "exercise api",
+    "exercise video api",
+    "fitness api",
+    "workout",
+    "claude"
+  ],
+  "homepage": "https://exercisebank.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/exercisebank/examples.git",
+    "directory": "packages/exercisebank-mcp"
+  },
+  "bugs": "https://github.com/exercisebank/examples/issues",
+  "mcpName": "io.github.exercisebank/exercisebank-mcp",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "exercisebank-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "exercisebank": "^0.1.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}