wunder-user-mcp

An MCP server that exposes the Wunder Mobility v2 end-user (User) API as tools. It lets an MCP client (Claude, etc.) browse vehicles, inspect and operate rentals, and create rentals/reservations on behalf of a single signed-in end user.

Authentication is handled entirely from a refresh token you provide via env var — the server exchanges it for short-lived access tokens and refreshes them automatically, so tool callers never deal with tokens.

Tools

Related MCP server: agentforge

Configuration

All configuration is via environment variables (see .env.example):

Getting a refresh token

Sign in once via the Wunder Authentication API (e.g. POST /{tenant}/auth/sign-in-email, /sign-in-phone-number, or /sign-in-api-client) and copy the refreshToken from the response into WUNDER_REFRESH_TOKEN.

Run

Run straight from the GitHub repo — no clone and no PyPI publish required (uvx builds from the Git source):

uvx --from git+https://github.com/slettmayer/wunder-user-mcp wunder-user-mcp

Pin a branch, tag, or commit for stability by appending @<ref>:

uvx --from git+https://github.com/slettmayer/wunder-user-mcp@main wunder-user-mcp

uvx caches the build, so to pick up new commits on a moving ref (e.g. @main) add --refresh:

uvx --refresh --from git+https://github.com/slettmayer/wunder-user-mcp@main wunder-user-mcp

From a local checkout (development):

uv run wunder-user-mcp        # editable install, reflects local edits
uvx --from . wunder-user-mcp  # build from the current directory

In all cases WUNDER_REFRESH_TOKEN and WUNDER_TENANT must be set in the environment (see Configuration). The server speaks MCP over stdio.

MCP client configuration

{
  "mcpServers": {
    "wunder-user": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/slettmayer/wunder-user-mcp",
        "wunder-user-mcp"
      ],
      "env": {
        "WUNDER_REFRESH_TOKEN": "<refresh-token>",
        "WUNDER_TENANT": "<tenant-code>",
        "WUNDER_BASE_URL": "https://go-staging.api.gourban.services/v1",
        "WUNDER_BRANCH_ID": "<optional-branch-id>"
      }
    }
  }
}

WUNDER_BASE_URL defaults to production (https://go.api.gourban.services/v1); the value above targets staging (go-staging). Set it to match your tenant's environment — a staging tenant on the production host returns 404. To pin a ref, append @<ref> to the URL, e.g. git+https://github.com/slettmayer/wunder-user-mcp@main.

Development

uv sync            # install deps (incl. dev group)
uv run pytest      # offline unit tests (geo + JWT exp parsing)
uv run ruff check  # lint

Notes / caveats

• The vehicle position field path used for distance calculation is detected best-effort (lat/lng, latitude/longitude, or a nested position/location). If a tenant's response uses different field names, extend geo.py.

• operation_type in rental_command is passed through to the API, so tenant-specific operations beyond the documented set keep working.

• Rental creation and END are high-impact: they can trigger vehicle commands, payment authorization/capture, deposits, and invoices.