wheel-size-mcp

The official MCP server for the Wheel Fitment API — built and maintained by Wheel-Size.com, the API provider. Gives LLM agents access to vehicle wheel and tire compatibility data.

Ask your AI assistant things like:

• "What are the OEM wheel specs for a 2024 Toyota Camry?"
• "Which vehicles fit 5x114.3 18x8 ET35 rims?"
• "Calculate plus-size options for 225/50R17 on 7Jx17 ET40"
• "Generate a product card for this wheel showing all compatible vehicles"

Quick Start

1. Get an API key

Sign up at developer.wheel-size.com and copy your API key.

2. Set the API key in your shell

Add to your ~/.zshrc (or ~/.bashrc):

export WHEELSIZE_API_KEY="your-api-key-here"

Then reload your shell: source ~/.zshrc

3. Add to your AI client

Choose your client below — each config block is copy-paste ready.

Claude Code

claude mcp add wheel-size-api -- uvx wheel-size-mcp

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "${WHEELSIZE_API_KEY}"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "wheel-size-api": {
      "command": "uvx",
      "args": ["wheel-size-mcp"],
      "env": {
        "WHEELSIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Zed

Add to your Zed settings.json (Cmd+, → Open Settings):

{
  "context_servers": {
    "wheel-size-api": {
      "command": {
        "path": "uvx",
        "args": ["wheel-size-mcp"],
        "env": {
          "WHEELSIZE_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

4. Restart your client

The MCP server starts automatically when the client launches.

Remote Server (Streamable HTTP)

Besides stdio, the server can run as a standalone HTTP service — useful for hosting one shared instance instead of installing Python on every machine:

wheel-size-mcp --transport http --port 8000

The MCP endpoint is served at http://127.0.0.1:8000/mcp/. Point HTTP-capable clients at it:

{
  "mcpServers": {
    "wheel-size-api": {
      "url": "http://127.0.0.1:8000/mcp/"
    }
  }
}

Security: the server binds to 127.0.0.1 by default. The WHEELSIZE_API_KEY lives on the server side, so anyone who can reach the port consumes your API quota — expose it beyond localhost (--host 0.0.0.0) only behind a reverse proxy that handles authentication.

Available Tools (22)

Catalog — vehicle lookup

Tool	Description
ws_list_makes	List all manufacturers. Start here.
ws_list_models	Models for a make (e.g. Toyota → Camry, Corolla…).
ws_list_years	Available years for a make/model.
ws_list_generations	Generations for a make/model (alternative to years).
ws_list_modifications	Trims for a specific vehicle (e.g. 2.0i, 3.0 V6…).
ws_list_regions	Market regions (USDM, EUDM, JDM…).

Search — fitment data

Tool	Description
ws_search_by_vehicle	OEM wheel/tire specs for a vehicle. Requires modification or region, plus year or generation (unless modification is given).
ws_search_by_rim	Find vehicles compatible with a rim (exact specs or min/max ranges).
ws_search_by_tire	Find vehicles by metric tire size, with speed/load/staggered filters and refinement facets.
ws_search_by_hf_tire	Find vehicles by high-flotation (LT) inch size (e.g. 31x10.50R15).
ws_check_rim_fitment_for_vehicle	"Will these rims fit my 2020 Civic?" — one-call fitment check.
ws_check_tire_fitment_for_vehicle	Same for a metric tire size.
ws_check_hf_tire_fitment_for_vehicle	Same for a high-flotation tire size.
ws_calculate_upsteps	Plus/minus sizing calculator: asymmetric diameter range (steps_min/steps_max), per-diameter counts, width/diameter tolerances.

Classified — product cards for e-commerce

Tool	Description
ws_find_tires_for_rim	Compatible tire sizes for a rim spec.
ws_find_vehicles_for_rim	Vehicles that fit a given rim (geometric 2D filtering).
ws_find_vehicle_modifications_for_rim	Drill down into trims for a specific generation.
ws_find_vehicles_for_tire	Vehicles that use a specific tire size.
ws_find_vehicle_modifications_for_tire	Drill down into trims for a generation that uses the tire.
ws_find_vehicles_for_package	Vehicles compatible with a rim + tire combo.
ws_find_vehicle_modifications_for_package	Drill down into trims for a rim + tire package.

Utility

Tool	Description
ws_get_spec_metadata	Computed geometry, population stats, and intelligence hints for any spec.

Engine and Powertrain Data

Since the API release of 2026-09-15, every modification row returned by ws_list_modifications, ws_search_by_vehicle and the ws_check_*_fitment_for_vehicle tools carries two sibling blocks:

• engine — the legacy block {fuel, capacity, type, power, code}, unchanged. engine.power is the headline figure whose source depends on the electrification level (combustion engine for combustion-only cars and mild hybrids, system power for full/plug-in hybrids and EVs). engine.fuel is a display string; group and filter on the powertrain fuel codes instead.
• powertrain — combustion_engine, electrification_level, primary_fuel, secondary_fuel, engine_power, system_power, engine_power_secondary, motors. ws_search_by_vehicle returns the block as the API sends it ({kW, PS, hp} power objects, {code, title} fuel refs); the list and fitment-check tools return a compact summary (hp figures, fuel codes, motors [{axle, hp, code}]) to stay within token limits.

Absence words in enums and fuel codes are data, not errors: not_applicable (cannot apply — a BEV has no engine), not_reported (applies, not recorded yet), unknown (neither electrification tier nor fuel recorded). engine_power is the combustion engine alone and is the figure most other vehicle-data providers publish as "power" (on bi-fuel vehicles it may still be the higher of the engine's two ratings while engine_power_secondary is being filled in); system_power is the manufacturer-declared total of the whole powertrain, normally null outside full/plug-in hybrids and EVs with a motor on each axle, and must never be reconstructed by adding engine and motor figures.

The fuel filter of ws_list_modifications takes fuel codes (biodiesel_blend, cng, diesel, e100, electric, ethanol_blend, flex_fuel, h2, hybrid, lpg, petrol, petrol_cng, petrol_lpg); one value matches the legacy engine.fuel, the primary fuel or the secondary fuel, and a real code read from powertrain.primary_fuel / secondary_fuel can be passed straight back. Older spellings such as natural-gas are still accepted; the absence words (not_applicable, not_reported, unknown) and anything else are a 400 error.

MCP Prompts

Pre-built workflow prompts that guide LLM agents through multi-step operations:

Prompt	Description
vehicle_fitment_lookup	Complete catalog→search chain for a vehicle description
rim_compatibility_check	Metadata→classified flow for rim compatibility
product_card_generation	E-commerce product card workflow for wheels/packages

Environment Variables

Variable	Required	Default	Description
WHEELSIZE_API_KEY	Yes	—	API key from developer.wheel-size.com
API_BASE_URL	No	https://api.wheel-size.com	API base URL
API_HOST_HEADER	No	—	Host header override (only needed for local Docker routing)
MCP_TRANSPORT	No	stdio	stdio or http (same as --transport)
MCP_HOST	No	127.0.0.1	Bind address for http transport (same as --host)
MCP_PORT	No	8000	Port for http transport (same as --port)

API Terms of Service

Search tools (ws_search_by_vehicle, ws_search_by_rim, ws_search_by_tire, ws_search_by_hf_tire, the ws_check_*_fitment_for_vehicle checks) and classified tools (ws_find_*) must be initiated by real users per API Terms of Usage. Do not call them in autonomous agent loops or for bulk data generation. Catalog tools, utility tools and ws_calculate_upsteps have no such restriction.

Evals

tests/test_questions.json contains 89 natural-language questions across 12 categories (catalog navigation, fitment lookups, reverse searches, fitment checks, upstep calculation, e-commerce product cards, spec metadata, multi-step workflows, edge cases, tool selection). Each entry includes expected_tools, optional expected_params / expected_params_search, and a free-text tests note.

evals/run_evals.py feeds these questions to a real Claude model with the MCP tools attached, records which tools it calls with which parameters, and grades them against the expectations — catching regressions in tool descriptions and server instructions:

# needs ANTHROPIC_API_KEY and a reachable Wheel Fitment API; costs money
uv sync --group evals
uv run --group evals python evals/run_evals.py                  # all questions
uv run --group evals python evals/run_evals.py -n 10            # smoke run
uv run --group evals python evals/run_evals.py --category catalog_flow
uv run --group evals python evals/run_evals.py --json report.json --min-pass 0.8

Grading is deterministic (no LLM judge): every expected tool must be called (multiset — repeats counted, extra navigation calls allowed), and some single call must carry the expected parameters. Questions without machine-checkable expectations are reported as SKIP and excluded from the pass rate. The default model is pinned (claude-sonnet-5) so pass-rate history stays comparable; override with --model.

The eval runner is not part of pytest or CI — it bills the Anthropic API. The grading logic itself is unit-tested in CI (tests/test_eval_grading.py). ToS note: every question simulates a user-initiated request, so the search-tool restriction is respected.

Development

# Install dev dependencies
uv sync --dev

# Unit tests (no API needed — this is what CI runs)
uv run pytest -m "not integration"

# Full test suite (requires a private API instance, see note below)
uv run pytest

# Lint
uv run ruff check .

# Run server (stdio)
wheel-size-mcp

Note on tests: integration tests run against a private test instance of the API and auto-skip when it is unreachable. External contributors should rely on the unit suite (pytest -m "not integration"), which mocks all HTTP and is what CI runs on every push and pull request.