VehicleAI MCP Server

An MCP (Model Context Protocol) server that exposes the iOS app's per-vehicle baselines, trip history, AI narratives, and live OBD readings to any MCP-aware client — Claude Desktop, Cursor, or OpenClaw.

Two paths, same tool surface

VehicleAI ships a dual-path server. Each tool call tries the live bridge first, then falls back to a disk snapshot when the phone is offline.

1. Live bridge — when the iOS app's Settings → MCP bridge toggle is on and your Mac can reach the phone (same Wi-Fi or Tailscale), every tool routes through an HTTP server hosted inside the VehicleAI app. This unlocks live PID reads, on-demand DTC scans, freeze-frame pulls, Mode 09 VIN reads — the complete OBD surface.
2. Snapshot fallback — when the bridge is unreachable, historical tools (recent_trips, baselines, daily_rollups, etc.) continue working against the JSON file the phone auto-exports after every trip. Live-only tools return a clear "phone is offline" message.

The phone is always authoritative — the snapshot is just what the phone last wrote down. There is no server, no cloud, no account.

Install

Python 3.10+:

pip install vehicleai-mcp

Or, from source (for development):

cd mcp-server
pip install -e .

Either path registers a vehicleai-mcp console script.

Configure

Live bridge (preferred)

On the phone: Settings → MCP bridge → enable, copy the token.

On the Mac (or wherever the MCP client runs), set two env vars:

export VEHICLEAI_BRIDGE_URL=http://<phone-ip>:50501
export VEHICLEAI_BRIDGE_TOKEN=<token from the app>
# Optional — default 6 seconds, raise if you're over a slow tailnet
export VEHICLEAI_BRIDGE_TIMEOUT=8

The phone's Settings UI lists every address it's reachable at (LAN IP, Tailscale IP, etc.). Pick whichever your MCP client can reach.

Snapshot fallback (recommended for offline resilience)

Even with the bridge configured, set one of the snapshot paths so historical queries work when the phone is asleep:

1. VEHICLEAI_SNAPSHOT_PATH — full path to the JSON file
2. VEHICLEAI_SNAPSHOT_DIR — directory containing VehicleAI-Latest.json
3. Default: ~/Library/Mobile Documents/com~apple~CloudDocs/VehicleAI-Latest.json (macOS iCloud Drive)

Point the iOS app's auto-export folder at the same location.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vehicleai": {
      "command": "vehicleai-mcp",
      "env": {
        "VEHICLEAI_BRIDGE_URL": "http://100.64.1.2:50501",
        "VEHICLEAI_BRIDGE_TOKEN": "REPLACE_WITH_TOKEN_FROM_APP",
        "VEHICLEAI_SNAPSHOT_PATH": "/Users/you/Library/Mobile Documents/com~apple~CloudDocs/VehicleAI-Latest.json"
      }
    }
  }
}

Restart Claude Desktop. The tools below appear in the MCP picker.

OpenClaw

{
  "mcp": {
    "vehicleai": {
      "transport": "stdio",
      "command": "vehicleai-mcp",
      "env": {
        "VEHICLEAI_BRIDGE_URL": "http://100.64.1.2:50501",
        "VEHICLEAI_BRIDGE_TOKEN": "REPLACE_WITH_TOKEN_FROM_APP",
        "VEHICLEAI_SNAPSHOT_DIR": "/Users/you/Dropbox/VehicleAI"
      }
    }
  }
}

Tools

Live (bridge-only)

Historical (bridge or snapshot)

Security notes

• The bridge binds to non-cellular interfaces only — LAN + Tailscale, never over your mobile data plan.
• Every authenticated request must carry a matching X-VehicleAI-Token header. Constant-time compare on the phone side.
• /health is unauth'd so clients can tell "phone is asleep" from "token is wrong" without leaking whether a token is provisioned.
• Rotate the token any time from the iOS app — invalidates every client config in one tap.

Running manually

VEHICLEAI_BRIDGE_URL=http://phone.tailnet:50501 \
VEHICLEAI_BRIDGE_TOKEN=... \
VEHICLEAI_SNAPSHOT_PATH=/path/to/VehicleAI-Latest.json \
vehicleai-mcp

The server speaks stdio — you'll only see output when a client connects and calls a tool. Use the MCP Inspector for local smoke testing:

npx @modelcontextprotocol/inspector vehicleai-mcp