vehicleai-mcp 0.1.0

MCP server exposing VehicleAI per-vehicle baselines, trip history, AI narratives, and live OBD reads to Claude Desktop / OpenClaw / Cursor

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)

Tool	Description
connection_status	Is the phone online? Is the OBD transport ready?
read_pid	Force-read a single PID from the ECU right now
read_pids	Force-read multiple PIDs in one pass
read_vin	Pull the VIN via Mode 09
read_dtcs	Active Diagnostic Trouble Codes (Mode 03)
read_pending_dtcs	Pending DTCs (Mode 07)
freeze_frame	Mode 02 freeze frame for the most recent DTC

Historical (bridge or snapshot)

Tool	Description
vehicle_status	Active vehicle identity + health verdict + live samples (when live)
recent_trips	Most recent finalized trips (newest first)
trip_narratives	AI-written 2-3 sentence trip summaries
baselines	Per-PID Welford stats — "what's normal for your car"
daily_rollups	Per-day aggregated driving stats
vehicles	Every VIN VehicleAI has seen

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