Wunder Mobility MCP

Give your AI coding assistant live knowledge of the Wunder Mobility API.

This is a Model Context Protocol (MCP) server that puts the full Wunder Mobility public API documentation — every guide, every endpoint, every request/response schema — directly inside your AI assistant.

Instead of copy-pasting docs or hoping your assistant's training data is up to date, you can just ask:

"What endpoints do I need to build a payment flow for my users?" "Show me the full spec for creating a booking." "How does vehicle discovery work in the User API?"

…and get back cited answers with deep-links straight to docs.wundermobility.services.

Works with Claude Code, Cursor, Windsurf, VS Code with Copilot, and any other MCP-compatible client.

What it does

The MCP server exposes twelve tools your assistant can call automatically. It reads like a book: the list first, then the outline of one document, then one section. For an exact code or name, a finder lists every place it appears.

Every result includes a deep-link so you (or your assistant) can open the same content in a browser.

Docs are pulled live from the public Wunder docs sites (api.docs.wundermobility.services and data.docs.wundermobility.services) on every startup and cached locally — so your assistant always has the current API and data-warehouse schema, not a stale snapshot. The fetch is unauthenticated and never committed.

Install

Option A — uvx (recommended, no cloning needed)

uvx runs the package directly from PyPI — no Python environment setup, no cloning.

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv
# or: winget install astral-sh.uv                  # Windows

Claude Code:

claude mcp add wunder-api uvx wunder-mobility-mcp

Cursor — add to your MCP settings (~/.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "wunder-api": {
      "command": "uvx",
      "args": ["wunder-mobility-mcp"]
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "wunder-api": {
      "command": "uvx",
      "args": ["wunder-mobility-mcp"]
    }
  }
}

Any client that accepts a command: use uvx as the command and ["wunder-mobility-mcp"] as the args.

On first start, the server fetches the latest docs from GitHub (~5–10s) and caches them locally. Every subsequent start is instant.

Option B — clone and run

If you'd rather run from source:

Prerequisites: Python 3.12+, git.

git clone https://github.com/Wunder-Mobility/public-api-mcp.git
cd public-api-mcp
make install

Claude Code:

claude mcp add wunder-api "$(pwd)/.venv/bin/wunder-mobility-mcp"

Cursor:

{
  "mcpServers": {
    "wunder-api": {
      "command": "/path/to/public-api-mcp/.venv/bin/wunder-mobility-mcp"
    }
  }
}

Replace /path/to/public-api-mcp with your actual clone path (pwd inside the repo).

Verify it's working

Once connected, open your assistant and try:

• "Search the Wunder API docs for payment flow"
• "List all endpoints in the Wunder operations API"
• "Get the guide for user authentication"

You should see the tools being called and results coming back with Stoplight links.

How docs stay current

The docs are published to the public GitHub Pages site api.docs.wundermobility.services (and data.docs.wundermobility.services for the Snowflake data docs). On every server startup, this MCP mirrors the latest raw docs from those sites — driven by each site's toc.json — and caches them locally. No authentication, no manual sync, no stale snapshots.

To get the latest docs locally: restart your MCP server (or restart your editor). The cache lives at:

Development

make install   # create .venv, install package + dev deps
make test      # run the test suite (requires network on first run)

make test fetches live docs from the public docs sites on the first run (~10s). Subsequent runs use the local cache.

Project structure

src/wunder_mcp/
  docs_source.py   # mirrors & caches the raw docs from the public Pages sites
  catalog.py       # builds the in-memory guide + endpoint catalog
  guide_tree.py    # a guide's table of contents: its sections and the text of each
  find.py          # exact-text finder (no ranking) over the API docs and the data docs
  docs_links.py    # parses toc.json and builds Stoplight deep-link URLs
  openapi.py       # loads and indexes OpenAPI specs
  server.py        # MCP tool definitions (FastMCP)
  stdio.py         # stdio entrypoint

Publishing a new version

1. Bump version in pyproject.toml
2. Commit and tag: git tag v0.x.x && git push --tags
3. The publish.yml workflow builds and uploads to PyPI automatically via trusted publishing

One-time PyPI setup (before the first publish): go to pypi.org → your project → Publishing → add a trusted publisher with owner Wunder-Mobility, repo public-api-mcp, workflow publish.yml, environment pypi.

Troubleshooting

Failed to reconnect to wunder-api: ENOENT

What it means: Your AI client tried to restart the wunder-api server process but couldn't find the uvx executable. This happens because desktop apps and some editors launch with a minimal PATH that doesn't include the directory where Homebrew or uv installed uvx.

Fix — use the absolute path to uvx:

1. Find where uvx lives on your machine:

   which uvx
   

   Common locations:

   • macOS (Apple Silicon / Homebrew): /opt/homebrew/bin/uvx
   • macOS (Intel / Homebrew): /usr/local/bin/uvx
   • Linux: ~/.local/bin/uvx

2. Re-register the server using that full path:

   Claude Code:

   claude mcp remove wunder-api
   claude mcp add wunder-api /opt/homebrew/bin/uvx wunder-mobility-mcp
   

   Cursor / Windsurf / other JSON configs:

   {
     "mcpServers": {
       "wunder-api": {
         "command": "/opt/homebrew/bin/uvx",
         "args": ["wunder-mobility-mcp"]
       }
     }
   }
   

   Replace /opt/homebrew/bin/uvx with the output of which uvx.

Roadmap

• v0.1: read-only API docs search, public and unauthenticated, docs fetched live on startup.
• v0.2: Snowflake data-warehouse documentation search — operators can discover tables, columns, and enum meanings for SQL building without leaving their AI assistant.
• v0.6 (current): read the docs by table of contents (list, outline, one section) with an exact-text finder for codes and names. Both word-match searches (search_guides_and_endpoints, search_snowflake_docs) and get_guide are removed.
• v1.0: tools that call the live Wunder API directly (e.g. create_test_booking), gated by a customer API key.