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

Tool	What it does	Underlying endpoint
get_vehicles	List available vehicles. With a latitude/longitude, annotates each vehicle with distance from the user and sorts ascending.	GET /vehicles
get_active_rental	Return the user's ongoing rental(s) (ACTIVE / RESERVATION).	GET /rentals
rental_command	Operate a rental: START, PARK, DRIVE, END, OPEN_TAILBOX, RENEW_RESERVATION, …	POST /rentals/{id}/operation
create_rental	Create a rental in RESERVATION or ACTIVE state from a vehicle_id or vehicle_code.	POST /rentals

Configuration

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

Variable	Required	Default	Purpose
WUNDER_REFRESH_TOKEN	✅	—	Long-lived refresh token for the end user.
WUNDER_TENANT	✅	—	Tenant short-code used in the API URL path.
WUNDER_BASE_URL		https://go.api.gourban.services/v1	API gateway base URL.
WUNDER_BRANCH_ID		—	Default branch id for vehicle/rental calls.
WUNDER_DEFAULT_RADIUS_MI		5	Radius (miles) used by get_vehicles when a location is given without a radius.
WUNDER_HTTP_TIMEOUT		30	Per-request timeout in seconds.

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.