ayhammouda/obd-mcp-server

A safety-first, local-first MCP server that gives AI clients structured,
read-only vehicle diagnostic observations without exposing raw protocol access
or state-changing operations.
Start with a deterministic simulator, optionally connect an ELM327 adapter,
and extend the server through normalized drivers and source-labeled diagnostic
profiles. The policy core remains authoritative regardless of the client,
driver, or profile.
> [!CAUTION]
> This is pre-release diagnostic software, not a safety system or a substitute
> for a qualified technician. It must never be used to decide that a vehicle is
> safe to drive. Do not connect development builds to a moving vehicle.
Why this project
- **Read-only by construction:** fixed diagnostic capabilities are enforced in
the core before a request reaches a driver.
- **Useful without hardware:** the simulator exercises the complete MCP path
on Linux and macOS.
- **Extensible without raw access:** drivers implement normalized reads, while
declarative profiles can only narrow allowlisted operations.
- **Data-conscious:** VIN-shaped values are rejected, outputs use a local
pseudonymous fingerprint, and bundled profiles require redistribution
provenance.
- **Built for review:** safety, privacy, legal/data, threat-model, packaging,
and supply-chain checks are part of the repository.
30-second simulator demo
Prerequisites: Python 3.11+ and uv.
The smoke command initializes a real MCP client session, lists the seven typed
tools, and discovers a synthetic vehicle without hardware. To start the server
for an MCP client, run uv run obd-mcp; stdio stdout is reserved for MCP
messages.
Current scope
The 0.1.x foundation provides:
- seven typed MCP tools for vehicle discovery, standard signal reads, DTC
reads, source-labeled ECU snapshots, and local issue timelines;
- a hard read-only policy with no raw request or fault-clearing surface;
- a built-in simulator so the complete MCP flow works without hardware;
- an optional py-obdii ELM327 integration; the extra installs its dependency,
and configuration validation does not import it or contact an adapter;
- an entry-point plugin API for future SocketCAN, ISO-TP, K-line, replay, and
vendor-neutral adapter packages, disabled unless the operator explicitly
opts in to trusted in-process plugin code;
- declarative, externally mounted profiles with provenance and redistribution
metadata;
- per-vehicle/per-ECU serialization, short-lived read caching, local SQLite
issue storage, and pseudonymous VIN fingerprints;
- stdio plus loopback-only Streamable HTTP transports.
It intentionally does **not** include OEM databases, copied standards content,
Renault/CLIP/DDT/PyRen data, ECU coding, clearing, flashing, actuator control,
security access, arbitrary CAN/UDS/KWP requests, remote HTTP access, or raw
capture.
Explore the checkout
Inspect the CLI and validate a configuration without connecting to a vehicle:
For built-in drivers, check-config validates the TOML schema, referenced
profiles, driver options, and optional dependency availability without
constructing a driver or connecting to a vehicle. It cannot establish that a
third-party plugin is safe or that live hardware will work.
Run loopback-only Streamable HTTP:
The MCP endpoint is http://127.0.0.1:8765/mcp. Non-loopback binds are
rejected because the server does not yet implement remote authentication.
MCP tools
| Tool | Behavior | Vehicle mutation |
|---|---|---|
| obd_list_vehicles | Lists configured vehicles and capabilities | None |
| obd_get_vehicle_status | Reports connection state and a pseudonymous VIN fingerprint/redacted suffix | None |
| obd_read_standard_pids | Reads only fixed, allowlisted Mode 01 PIDs | None |