@musclewiki/mcp

First-party Model Context Protocol (MCP) server for the MuscleWiki API. It exposes the exercise database (1,900+ exercises with video demonstrations) to LLM clients — Claude Desktop, Claude Code, Cursor, and any other MCP-compatible host — as native tools.

The server runs locally over stdio and forwards every call to the public REST API using your own MuscleWiki API key. There is no hosted infrastructure and no shared/privileged key: your subscription tier, rate limits, and quotas apply exactly as they would for direct API calls.

Requirements

• Node.js >= 18
• A MuscleWiki API key (get one at https://api.musclewiki.com) on the TESTING tier or higher — every tool calls a direct REST endpoint, so a BASIC-tier key (playground-only) is rejected with a 403 on every call. The routine & workout tools additionally require the PROFESSIONAL or ENTERPRISE tier; lower tiers receive a clear 403 tool error explaining the requirement.

Tools

| Tool | REST endpoint | Description | |---|---|---| | search_exercises | GET /search | Full-text search by name/steps with optional filters (q 2-200 chars, limit 1-50, category, muscles, secondary_muscles, tertiary_muscles, difficulty). | | list_exercises | GET /exercises | Browse/filter exercises with pagination. No query term required (category, muscles, secondary_muscles, tertiary_muscles, difficulty, force, mechanic, grips, gender). | | get_exercise | GET /exercises/{id} | Fetch one exercise by numeric ID (IDs are non-consecutive integers >= 1). | | list_categories | GET /categories | Equipment categories with exercise counts. | | list_muscles | GET /muscles | Primary muscle groups with exercise counts. | | list_filters | GET /filters | All valid filter values (muscles, secondary_muscles, tertiary_muscles, difficulties, forces, mechanics, grips, categories). Call this to avoid guessing filter arguments. | | get_random_exercise | GET /random | A random exercise, optionally filtered by equipment category. | | get_statistics | GET /statistics | Aggregate database statistics. | | list_routines | GET /routines | Paginated routines (id, name, slug, difficulty). PROFESSIONAL/ENTERPRISE. | | get_routine | GET /routines/{id} | A routine with its workout references. PROFESSIONAL/ENTERPRISE. | | get_routine_full | GET /routines/{id}/full | A routine with all workouts & exercises expanded in one request, billed as one call per routine, workout and exercise it contains (X-API-Calls-Cost). PROFESSIONAL/ENTERPRISE. | | list_workouts | GET /workouts | Paginated workouts with filters (difficulty, goal, equipment, muscles). PROFESSIONAL/ENTERPRISE. | | get_workout | GET /workouts/{id} | A workout with exercise references and prescription data. PROFESSIONAL/ENTERPRISE. | | get_workout_full | GET /workouts/{id}/full | A workout with all exercises expanded in one request, billed as one call per workout and exercise it contains (X-API-Calls-Cost). PROFESSIONAL/ENTERPRISE. |

Secondary and tertiary muscles. On the PROFESSIONAL plan and above, exercises returned by search_exercises, get_exercise, get_random_exercise and the *_full tools also list secondary_muscles and tertiary_muscles. On lower plans both are null. The secondary_muscles and tertiary_muscles filters on search_exercises and list_exercises need the same plan; on a lower plan setting either one returns a 403 tool error.

Errors (invalid/missing key, 403 tier restriction, 429 monthly quota, 422 validation, 404 not-found, network/timeout) are surfaced to the client as clear tool errors — the server never crashes on them. Your API key is never logged or included in any error message.

Configuration

| Env var | Required | Default | Description | |---|---|---|---| | MUSCLEWIKI_API_KEY | yes | — | Your MuscleWiki API key, sent as the X-API-Key header. | | MUSCLEWIKI_BASE_URL | no | https://api.musclewiki.com | Override the API base URL (e.g. for local testing). |

Setup

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "musclewiki": {
      "command": "npx",
      "args": ["-y", "@musclewiki/mcp"],
      "env": {
        "MUSCLEWIKI_API_KEY": "<your-api-key>"
      }
    }
  }
}

Restart Claude Desktop. The MuscleWiki tools appear in the tools menu.

Claude Code

claude mcp add musclewiki --env MUSCLEWIKI_API_KEY=<your-api-key> -- npx -y @musclewiki/mcp

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "musclewiki": {
      "command": "npx",
      "args": ["-y", "@musclewiki/mcp"],
      "env": {
        "MUSCLEWIKI_API_KEY": "<your-api-key>"
      }
    }
  }
}

Other MCP clients

MCP is an open standard — the same server works with every MCP-compatible host. Only the config location (and, for a couple of clients, the wrapper key) differs; the command/args/env are always identical:

| Client | Config location | Wrapper key | |---|---|---| | Claude Desktop | claude_desktop_config.json | mcpServers | | Cursor | ~/.cursor/mcp.json (or project .cursor/mcp.json) | mcpServers | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | | VS Code (Copilot) | .vscode/mcp.json | servers | | Zed | settings.json | context_servers | | Cline / others | that client's MCP settings | usually mcpServers |

VS Code and Zed use a different top-level key (servers / context_servers), but the inner server entry — command, args, env — is exactly the block shown above. For any client not listed, see its MCP docs and reuse the same command/args.

Replace <your-api-key> with your real key. Never commit the key to version control — it lives only in your client config / environment.

Usage

Once connected, just ask in plain language — the assistant picks the right tool and chains calls as needed. No need to name tools or endpoints yourself. For example:

• "Find me five dumbbell exercises for biceps."
• "What equipment categories are available, and how many exercises does each have?"
• "Show me a random bodyweight exercise with its instructions."
• "List all the valid difficulty and force filter values." (calls list_filters)
• "Get exercise 42 and summarise its steps."
• "Build me a beginner push/pull routine." (PROFESSIONAL/ENTERPRISE — uses list_workouts / get_workout_full)

A good pattern the model follows automatically: call list_filters first to learn the exact accepted filter strings, then search_exercises / list_exercises with those values, then get_exercise for full detail on a specific result.

Troubleshooting

| Symptom | Cause | Fix | |---|---|---| | Every tool errors with "MUSCLEWIKI_API_KEY environment variable is required" | The env var never reached the server process. | Set MUSCLEWIKI_API_KEY in the env block of your MCP client config (not just your shell). Restart the client. | | 403 on every call, detail "Invalid or expired API key" | Invalid, revoked, or mistyped key (the API returns 403, not 401, for a bad key). | Copy a fresh key from your dashboard at https://api.musclewiki.com. Keys start with mw_. | | 403 on every call, detail mentions tier/playground | BASIC-tier key (playground-only, no direct API access). | Upgrade to TESTING or higher. | | 403 only on routine/workout tools | Those tools require PROFESSIONAL or ENTERPRISE. | Upgrade, or use the exercise tools, which work on TESTING+. | | 429 errors | Monthly quota exceeded. | Resets at the start of your next billing cycle, or upgrade your tier for a higher quota. | | Server never starts / npx cannot find the package | Node.js < 18, or offline/registry issue. | Ensure Node.js >= 18 (node -v) and that npm can reach the registry. |

Your API key is never logged and never appears in any error message.

Versioning

Published to npm as @musclewiki/mcp and versioned with semantic versioning. Using npx -y @musclewiki/mcp (as shown above) always resolves the latest release.

Running locally (without publishing)

From a clone of the repo:

cd sdks/mcp
npm install
npm run build
MUSCLEWIKI_API_KEY=<your-api-key> node dist/index.js
# or, equivalently:
MUSCLEWIKI_API_KEY=<your-api-key> npx .

Development

npm install
npm run build       # bundle to dist/index.js (executable, with shebang)
npm test            # vitest (HTTP fully mocked; no live API/key needed)
npm run typecheck   # tsc --noEmit

License

MIT