wger MCP server

An MCP server that exposes the wger (>= 2.7) fitness/nutrition REST API as tools (routines, workout logging, exercise & ingredient catalog, nutrition plans + meals + recipes, diary, body-weight tracking, gym equipment, body measurements, volume/PR analytics, daily calorie calculator, …) so that AI assistants can read and write your wger data.

It talks to a wger instance over its public REST API — it is a separate service and requires no changes to wger itself.

• Transport: stdio for a local server your MCP client spawns, or Streamable HTTP (FastMCP) for a shared deployment. Pick with --transport.
• Auth: multi-user — every request acts as the calling user's own wger account. wger is itself the OAuth2/OIDC provider, so nothing else is needed (MCP_AUTH=wger_oidc); behind an existing SSO, an external OIDC IdP does the same job with a token exchange (MCP_AUTH=oidc). For single-user self-hosting, MCP_AUTH=static_token takes a shared secret plus your wger API key instead.
• Requires: wger >= 2.7, Python >= 3.11. The server reads wger's version once at startup and warns if it is older than the API client expects (the major and minor of the installed wger-api-client), naming both. It warns rather than refuses: the exercise and ingredient catalogs are stable across releases and keep working, while the tools built on newer endpoints fail visibly when called.

How auth works

This section describes the HTTP deployment, where several people share one server. Running locally over stdio? None of it applies — skip to Quick start — local, over stdio, where a wger API key is the only credential.

Every request acts as the calling user's own wger account, so the server needs a per-user wger credential. Where that comes from is the one real choice, and wger 2.7 changed the answer.

On wger >= 2.7 — MCP_AUTH=wger_oidc, the short path. wger is itself an OAuth2/OIDC provider and its REST API accepts the access tokens it issues. There is nothing to broker: the caller's token goes back out unchanged.

client → MCP    Authorization: Bearer <wger token>   (via MCP-native OAuth)
MCP → wger      Authorization: Bearer <the same token>  on /api/v2/*

No identity provider, no client credentials, no exchange — WGER_BASE_URL is the entire configuration. Because the login runs in the user's browser through wger's own login page, MFA enrolled in wger simply works. The tokens are opaque, so this server does not validate them: wger decides on every call whether a token is live and which scopes it carries. See docs/adr/0005-native-wger-oidc.md.

On wger 2.6, or behind an existing SSO — MCP_AUTH=oidc. wger 2.6 issues its own JWTs and its API accepts only wger-native credentials, so an IdP token has to be traded for one:

client → MCP    Authorization: Bearer <OIDC token>   (via MCP-native OAuth, or sent directly)
MCP             validates the token against the IdP's JWKS
MCP → IdP       RFC 8693 token-exchange → access_token aud'd at wger's OIDC client
MCP → wger      POST /allauth/app/v1/auth/provider/token  → a wger JWT
MCP → wger      Authorization: Bearer <wger JWT>  on /api/v2/*   (cached ~5 min per user)

Provider-agnostic: JWKS/token endpoints come from the IdP's discovery document ({issuer}/.well-known/openid-configuration). No per-user secrets are stored — the wger access token is cached in memory and re-derived on expiry. See docs/adr/0001-multi-user-auth-via-oidc-token-exchange.md.

Either way this server stores nothing: no database, no per-user secrets on disk.

Install

The server is published on PyPI as wger-mcp:

uvx wger-mcp

uvx runs it without installing anything permanently; pip install wger-mcp (or uv tool install wger-mcp) puts the same wger-mcp command on your PATH. A container image is published as ghcr.io/wger-project/mcp-server — see Deployment.

Quick start — local, over stdio

For your own account on your own machine. The MCP client starts the server as a child process and talks to it over a pipe, just point it at a wger instance and give it an API key (wger → Settings → API key):

{
  "mcpServers": {
    "wger": {
      "command": "uvx",
      "args": ["wger-mcp", "--transport", "stdio"],
      "env": {
        "WGER_BASE_URL": "https://wger.de",
        "WGER_API_KEY": "<your wger API key>"
      }
    }
  }
}

That is the whole configuration. WGER_API_KEY is the one credential involved; it acts as your wger account, so treat it like a password.

From a clone instead of PyPI, --directory is required — uv run looks for the project in the working directory, which belongs to the client that spawned it, not to you:

"command": "uv",
"args": [
  "run",
  "--directory", "/absolute/path/to/mcp-server",
  "wger-mcp",
  "--transport", "stdio"
]

A few notes specific to this mode:

• MCP_AUTH does not apply — there is no inbound request to authenticate. Setting it to oidc is refused at startup rather than failing later on the first tool call.
• No .env is read. The working directory belongs to whichever client spawned the process, so a stray file there must not silently configure the server. Pass --env-file PATH if you do want one. For the same reason the transport itself cannot come from such a file — only from --transport or the environment — and an env file that sets MCP_TRANSPORT is refused at startup rather than ignored.
• Logs go to stderr; your client shows them in its MCP log. stdout is the JSON-RPC stream and carries nothing else.
• MCP_TOOLS works here too — see Registering only some groups if the full set of 78 tools is more than your model handles well.

Quick start — shared deployment, over HTTP

Configuration comes from environment variables, or from a .env file in the directory you start the server in. .env.example documents every setting.

curl -O https://raw.githubusercontent.com/wger-project/mcp-server/master/.env.example
mv .env.example .env
# Edit .env. Against wger >= 2.7 that is two lines:
#   MCP_AUTH=wger_oidc
#   WGER_BASE_URL=https://wger.de
uvx wger-mcp

Server listens on http://0.0.0.0:8765, MCP endpoint at /mcp.

On wger 2.6, or with an existing SSO in front, set MCP_AUTH=oidc instead and fill in OIDC_ISSUER, OIDC_CLIENT_ID/SECRET and WGER_OIDC_AUDIENCE — see oidc.

Just trying it against your own account? The static_token strategy needs only a wger API key and no IdP:

# In .env: MCP_AUTH=static_token, MCP_STATIC_TOKEN=$(openssl rand -hex 32),
#          WGER_API_KEY=<your wger API key>, WGER_BASE_URL=<your wger>
uvx wger-mcp

Running from a checkout instead (for development, see CONTRIBUTING.md):

git clone https://github.com/wger-project/mcp-server.git
cd mcp-server
uv sync
cp .env.example .env
uv run wger-mcp

Prerequisites for MCP_AUTH=oidc (external IdP)

Only for the external-IdP mode. Under wger_oidc none of this applies — the prerequisites there live in wger, and are listed in that section.

• wger is configured with your IdP as an OIDC social-login provider (WGER_SOCIAL_PROVIDERS), so provider/token accepts its tokens. WGER_ALLAUTH_PROVIDER must match wger's provider id — the slug in wger's SocialApp (e.g. keycloak or openid_connect); it's the <id> in the OAuth callback path /account/oidc/<id>/login/callback/.
• IdP has a confidential client for this server (OIDC_CLIENT_ID / OIDC_CLIENT_SECRET) with token-exchange (RFC 8693) enabled and permitted to exchange to wger's client audience (WGER_OIDC_AUDIENCE). On Keycloak that means enabling Standard Token Exchange and adding an Audience mapper that includes the wger client (otherwise the exchange fails with Requested audience not available).
• MFA is delegated to the IdP. wger 2.6's headless provider/token enforces wger-side MFA: a user with a TOTP/WebAuthn authenticator enrolled in wger cannot complete the server-side login (no setting skips it). Users must rely on the IdP for MFA and not enroll wger-side 2FA. If wger-enforced MFA is a hard requirement, use per-user wger API keys instead of this exchange model.

Inbound auth strategies

Pick one with MCP_AUTH=. The server gates every request to /mcp/*. /health, /.well-known/* and the AS-facade endpoints (/authorize, /token by default) are always public.

oidc remains the built-in default so that no existing deployment changes behaviour on upgrade. New deployments against wger >= 2.7 should set MCP_AUTH=wger_oidc explicitly.

wger_oidc — wger is the provider (recommended)

Takes the caller's wger access token and puts it on the outbound API call unchanged. The whole configuration:

MCP_AUTH=wger_oidc
WGER_BASE_URL=https://wger.example.com
MCP_PUBLIC_URL=https://mcp.example.com   # this server's public base URL
#MCP_WGER_SCOPES=openid api:read api:write   # what to ask wger for (default)
#MCP_OIDC_ALLOWED_USERS=alice,bob            # optional allowlist

At wger the provider has to be switched on (IDP_OIDC_PRIVATE_KEY, from ./manage.py generate-oidc-key) and, unless dynamic client registration is enabled there, an OAuth client row has to exist for each MCP client — see wger's docs/administration/oauth2_provider.rst. wger's authorize/token endpoints are read from its discovery document at {WGER_BASE_URL}/.well-known/openid-configuration.

Notes on what this mode does and does not do:

• The token is checked with wger. wger's access tokens are opaque, so the server asks wger's /api/v2/userprofile/ whether a token is live and caches a positive answer for 60 seconds — keyed by a SHA-256 fingerprint, never by the token. A dead token is answered with 401 invalid_token, which is what makes an MCP client refresh it; if wger cannot be reached the answer is 503, so a client does not throw away a token that may be fine.
• Scopes. wger gates reads behind api:read and every write behind api:write; openid identifies the user. A grant that is missing one produces a 403 naming the scope, which the tools surface with a re-authorize this connection hint rather than as a generic failure. api:read is required, since every token is checked by reading the caller's profile. For a read-only deployment, drop api:write from MCP_WGER_SCOPES and pair it with a read-only MCP_TOOLS selection.
• MFA works. The authorization-code flow runs in the user's browser against wger's own login, so TOTP/WebAuthn enrolled in wger applies. This is the one thing the token-exchange mode cannot do.
• The allowlist is free. MCP_OIDC_ALLOWED_USERS is checked against the username that same lookup returns.
• If wger is reached over an internal URL, set OIDC_AUTHORIZATION_ENDPOINT to wger's public authorize URL: /authorize is followed by the user's browser, and discovery against an internal hostname returns internal URLs.

oidc — an external IdP

Validates an IdP-issued Bearer token against the IdP's JWKS, then exchanges it for a wger credential (see How auth works). Use this for wger 2.6, or where an SSO provider already fronts everything.

MCP_AUTH=oidc
OIDC_ISSUER=https://idp.example.com/realms/main   # or https://tenant.auth0.com/
MCP_OIDC_USERNAME_CLAIM=preferred_username  # which claim names the user
#MCP_OIDC_AUDIENCE=wger-mcp                  # if set, inbound aud/azp must match
#MCP_OIDC_ALLOWED_USERS=alice,bob            # optional allowlist

# This server as a confidential OIDC client (token-exchange):
OIDC_CLIENT_ID=wger-mcp
OIDC_CLIENT_SECRET=...
WGER_OIDC_AUDIENCE=wger                      # = wger's OIDC client id at the IdP
WGER_ALLAUTH_PROVIDER=openid_connect         # wger's allauth provider id (slug)

JWKS and token endpoints are resolved from the IdP's discovery document (override with OIDC_JWKS_URI / OIDC_TOKEN_ENDPOINT). Verified on the inbound token: signature (via JWKS), iss, exp, and — if MCP_OIDC_AUDIENCE is set — aud (or azp, which some IdPs use). JWKS is cached for MCP_JWKS_TTL_SECONDS (default 3600 s) and re-fetched on signature failure to handle key rotation.

Interactive MCP clients discover the IdP via OAuth Protected Resource Metadata at /.well-known/oauth-protected-resource (a 401 also advertises it in WWW-Authenticate). Set MCP_PUBLIC_URL to the externally reachable base URL so the advertised resource identifier is correct.

Authorization-Server facade

Applies to both OAuth modes. Some MCP clients — notably claude.ai's custom connector — do not follow the authorization_servers pointer to a different host. They treat the MCP server's own origin as the OAuth authorization server: they fetch {origin}/.well-known/oauth-authorization-server and run /authorize + /token against that origin. They also need the OAuth endpoints reachable from where the client runs — for a cloud client like claude.ai, the public internet — while the IdP itself can stay private.

To support this, the server exposes a thin AS facade in both OAuth modes (wger_oidc and oidc):

The facade paths default to the conventional /authorize, /token and /register — clients like claude.ai assume those and ignore the authorization_endpoint in the AS metadata. Override with OAUTH_AUTHORIZE_PATH / OAUTH_TOKEN_PATH / OAUTH_REGISTER_PATH if a client expects something else (no rebuild needed).

Set MCP_AS_FACADE=false to switch the facade off entirely: the metadata then names the provider directly and this origin serves no OAuth endpoints. Correct only if every client you care about follows the authorization_servers pointer — claude.ai does not. The pointer is the provider's issuer as its discovery document states it, so under wger_oidc WGER_BASE_URL has to be wger's public URL for this to work.

Scopes and registration under wger_oidc

Two things the facade does only in this mode, both for the same reason — a generic MCP client has no way of knowing that wger's API is gated behind api:read/api:write:

• /register is advertised and proxied when wger has dynamic client registration switched on (it publishes a registration_endpoint in its discovery document exactly then, so there is nothing to configure here). With DCR the connector flow is one URL; without it, every client needs an OAuth client row created in wger by hand.
• The API scopes are added to the proxied registration and to the /authorize query, on top of whatever the client asked for. A client that registers with openid alone is otherwise refused at /authorize with invalid_scope — allauth requires the requested scopes to be a subset of the client's — and nothing in that failure tells anyone why. What the facade adds is exactly what the consent screen then shows the user.

Reachability and endpoints

The provider never has to be publicly reachable: the user's browser reaches it for the login redirect, and the back-channel requests are proxied through this server. Tokens are still minted by the provider, so nothing about how they are checked changes. Its authorize/token endpoints come from discovery — of WGER_BASE_URL under wger_oidc, of OIDC_ISSUER under oidc — and are overridable with OIDC_AUTHORIZATION_ENDPOINT / OIDC_TOKEN_ENDPOINT in either mode. See docs/adr/0003-oauth-authorization-server-facade.md.

MCP_PUBLIC_URL must be set to the externally reachable base URL so the advertised endpoints point at the public origin (otherwise they're derived from the request's X-Forwarded-* / Host).

Adding the connector in claude.ai

Under wger_oidc:

1. In wger, create an OAuth client with redirect URI https://claude.ai/api/mcp/auth_callback (CONFIDENTIAL, scopes openid api:read api:write) — see wger's oauth2_provider docs. Skip this if wger has dynamic client registration enabled; the connector then registers itself through /register.
2. In claude.ai → Add custom connector: URL https://<public-host>/mcp. With a hand-made client, put its id and secret under Advanced settings.
3. Approve the consent screen wger shows. It names the scopes, which is the only moment the user sees that they are granting write access to their training, nutrition and body data.

Under oidc:

1. At the IdP, the confidential client (OIDC_CLIENT_ID) needs redirect URI https://claude.ai/api/mcp/auth_callback and web origin https://claude.ai, plus Standard flow and the token-exchange / audience-mapper setup from Prerequisites above.
2. In claude.ai → Add custom connector: URL https://<public-host>/mcp; under Advanced settings set Client ID / secret to the IdP client's.

Either way, verify discovery before connecting:

curl -s https://<public-host>/.well-known/oauth-protected-resource | jq
curl -s https://<public-host>/.well-known/oauth-authorization-server | jq

The interactive /authorize step 302s the browser to the provider, so the browser must reach it. With a split-horizon / LAN-only provider that means running the browser on that network; the back-channel /token is always proxied through this server.

static_token — single-user, no IdP required

For self-hosting where standing up an IdP is overkill. Callers present a shared secret as a bearer token; the server validates it (constant-time) and then calls wger with your personal DRF API key (Settings → API → "API key").

MCP_AUTH=static_token
MCP_STATIC_TOKEN=<openssl rand -hex 32>
WGER_API_KEY=<your personal wger API key>

The client sends Authorization: Bearer <MCP_STATIC_TOKEN>.

Unlike none, inbound requests are authenticated, so this is safe to expose over TLS. Caveats:

• Single-user. Every authenticated caller acts as the one wger account behind WGER_API_KEY. Use oidc if more than one person needs access.
• The secret is a password. It grants full access to that account; rotate it by changing the env var and restarting.
• Minimum 32 characters, enforced at startup — a guessable secret is the entire attack surface.
• No MCP-native OAuth. The OAuth discovery endpoints are deliberately not served under this strategy (a client following them would run a flow whose token this server never accepts), so configure the token out-of-band in your client.

none — no inbound authentication

Anyone who can reach /mcp acts as the account behind WGER_API_KEY — no credential required. The server logs a warning at startup.

MCP_AUTH=none
WGER_API_KEY=<your personal wger API key>

Safe only when bound to localhost for local development. Never expose it to a network, even behind TLS — use static_token instead if you need remote access.

Tools

Tools are grouped by domain. Each lives in its own module under src/wger_mcp/tools/.

Registering only some groups

All 85 tools are registered by default, which is about 18.6k tokens of schema in every request before the conversation starts. MCP_TOOLS narrows that to a comma-separated list of groups:

MCP_TOOLS=nutrition,off,exercises,profile

Valid names are the module names — profile, routines_read, routines_write, workout_logs, workout_sessions, body_weight, measurements, equipment, nutrition, exercises, analytics, off — plus routines, which means both routine halves. An unknown name stops the server at startup rather than silently dropping tools, and repeated names are harmless.

This matters most for agents driven by small local models, whose tool-selection accuracy falls off as the surface grows, and where every schema is spent from a modest context window. It is also useful for a single-purpose agent that has no business writing routines.

Profiles that cover most agents

Measured, not estimated: the token figures are the serialised tool list divided by four. They include the output schemas the MCP SDK now emits for every tool, which is why they are around a quarter higher than in earlier releases — the tool descriptions themselves did not grow by that much.

The training-plan tree is the largest group and splits in two: routines_read (9 tools, ~1.5k) reads the plan and answers what it prescribes today, routines_write (16 tools, ~4.7k) creates and changes it. An agent that follows a plan needs only the first, which is a fifth of the whole surface saved. routines remains valid and still means both.

Profile

Routines (training plan tree)

Workout logs

Workout sessions

The training unit a day's sets belong to. wger opens one implicitly for a log that names none, so these tools are what make its own fields reachable — when it ran, how it felt, and what the trainee wants to remember about it.

Body weight

Since wger 2.7 a body weight is a measurement like any other, in an official body_weight category every account has from registration. These tools go through /api/v2/measurement/ rather than the older /weightentry/ shim, which is what lets the unit travel with the reading: the shim reads and writes in whatever the profile says at that moment, so switching a profile from kg to lb reinterprets everything written before it.

For a trend rather than the entries, summarize_measurements works over this category like any other.

Body measurements

Categories, each with its unit, and the entries that hang off them. Since wger 2.7 a category carries a metric_type saying what it holds: the free-form ones a trainee invents (Waist, Chest, Bicep, … all custom) sit alongside typed ones for body weight, body fat, height, heart rate, blood pressure, sleep, steps and the rest. Three kinds do not take entries directly — the group containers (blood_pressure, sleep), whose readings belong in their component children, and the calculated ones (dynamic_type other than NONE, e.g. BMI), which the server maintains.

Blood pressure

A reading is two entries — systolic and diastolic — in two child categories of a blood_pressure group, paired by carrying the exact same timestamp. These two tools are what make that workable; doing it through log_measurement means finding both categories and matching timestamps by hand.

Exercise catalog

Ingredients

wger's REST /ingredient/ is read-only by design (community-maintained DB), so there is no create_ingredient tool. Submitting custom ingredients previously drove wger's Django web form with username/password; that path was dropped with the move to multi-user SSO auth.

Nutrition plans, meals, recipes, diary

Analytics

Open Food Facts (external food database)

Use these when you have a barcode — far more accurate than wger name search. Coverage is good for branded packaged goods and thin for supermarket private-labels, and it varies a lot by country. For items missing on OFF, the response includes a suggestion URL to add them — additions flow back into wger via the next ingredient-sync.

Language. OFF stores per-language fields (product_name_<lang>, ingredients_text_<lang>). Which one is requested and preferred comes from DEFAULT_LANGUAGE (default en), and every tool with a language argument overrides it per call. The response echoes the resolved language and carries both name_localized and the language-neutral name_default.

Configuring a client

Interactive (MCP-native OAuth)

Point the client at the Streamable HTTP URL. On first use it fetches /.well-known/oauth-protected-resource, runs the OAuth flow against the provider — wger itself under wger_oidc — and attaches the resulting Bearer token automatically.

{
  "mcpServers": {
    "wger": {
      "type": "streamable-http",
      "url": "https://wger-mcp.example.com/mcp"
    }
  }
}

Scripts / headless (manual Bearer)

Obtain a token out-of-band and pass it as Authorization: Bearer <token>. See scripts/get_token.py for a device-flow example.

Under wger_oidc that is a wger access token — from any of wger's own grants, the device-code flow included — and it is used as-is. Under oidc it is an IdP token whose audience must be acceptable to the server (MCP_OIDC_AUDIENCE), which the server then exchanges for a wger credential.

Deployment

CI publishes a multi-arch image to the GitHub Container Registry on every push to the default branch and on v*.*.* tags:

docker pull ghcr.io/wger-project/mcp-server:latest

A reference Docker setup ships in Dockerfile and compose.example.yml. The server is a single ASGI app (wger_mcp.server:build_app) and can also be run under any ASGI host (Hypercorn, Granian, gunicorn-uvicorn, …).

If exposed over HTTPS via a reverse proxy, configure the proxy with:

proxy_buffering off;
proxy_request_buffering off;
proxy_read_timeout 3600s;

so that streamable-HTTP/SSE responses aren't buffered.

Documentation

• CONTRIBUTING.md — development setup, project layout, how to add a tool or an auth strategy.
• docs/api-keys.md — which credential goes where, and a 401 troubleshooting table.
• CONTEXT.md — glossary of the terms used across these docs.
• docs/HANDOFF.md — maintainer notes: non-obvious constraints, open items, and known limitations.
• docs/adr/ — architecture decisions and the reasoning behind them:
  • 0001 — multi-user access via OIDC token exchange
  • 0002 — opaque string resource ids
  • 0003 — the OAuth authorization-server facade
  • 0004 — the static_token strategy
  • 0005 — native wger OIDC, superseding the transport half of 0001

Development

uv sync --dev
uv run pytest        # inbound auth (all four strategies), token exchange, wger client, tools
uv run ruff check .

Source layout

• src/wger_mcp/server.py — Starlette + FastMCP wiring, lifespan, healthcheck, OAuth metadata, auth middleware.
• src/wger_mcp/api_client.py — bridge to the generated wger-api-client: resolves the per-request wger credential from the token provider via a custom httpx auth, plus offset pagination over the generated *_list endpoints.
• src/wger_mcp/auth/ — inbound OIDC validation (oidc.py, discovery in oidc_discovery.py), token exchange + outbound credential provider (exchange.py), per-request identity (identity.py), OAuth metadata (oauth.py).
• src/wger_mcp/tools/ — one module per domain. Each exposes register(mcp, api, settings); tools/__init__.py registers them all.

Performance notes

• nutrition_summary, list_slot_entry_configs, _load_ex_meta (used by volume_trend / compare_periods) fan out per-id fetches via asyncio.gather + a small Semaphore. Concurrency caps live in the tool modules — tune down if your wger instance applies per-token rate limits.
• Exercise metadata is cached process-wide (_EX_META_CACHE in tools/analytics.py) — analytics tools called repeatedly within one process pay the metadata cost only once.
• compare_periods issues two range queries in parallel and skips fetching the gap window entirely.

Upgrading

Language is now configurable (was hard-coded Polish)

The Open Food Facts tools used to always request the Polish fields (product_name_pl, ingredients_text_pl), and the exercise/ingredient search tools defaulted to en. Both now follow DEFAULT_LANGUAGE (default en), with a per-call language argument overriding it.

• To keep the previous OFF behaviour, set DEFAULT_LANGUAGE=pl. Otherwise barcode lookups return English names where a Polish one used to be preferred.
• Response keys changed on lookup_food_by_barcode / lookup_foods_by_barcodes: name_pl → name_localized, ingredients_text_pl → ingredients_text, plus a new language field echoing the resolved code. name, name_default and the macro fields are unchanged.

License

AGPL-3.0-or-later, matching the wger project. See LICENSE.