shadetree-ai

Name: shadetree-ai
Author: Neil Roberts

Read-only OBD-II diagnostics for Claude: trouble codes, freeze frame and live engine data

By Neil Roberts (individual) Python Local · stdio Data and analytics

GitHub Website

17 popularity score ★ 25

Connect your client

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs SHADETREE_PORT. Replace each <NAME> with your value.

FirstTerminal

pipx install https://github.com/iamneilroberts/shadetree-ai/archive/refs/heads/main.zip

Claude CodeTerminal

claude mcp add shadetree-ai -e SHADETREE_PORT=<SHADETREE_PORT> -- shadetree-ai-mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "shadetree-ai": {
      "command": "shadetree-ai-mcp",
      "args": [],
      "env": {
        "SHADETREE_PORT": "<SHADETREE_PORT>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "shadetree-ai": {
      "command": "shadetree-ai-mcp",
      "args": [],
      "env": {
        "SHADETREE_PORT": "<SHADETREE_PORT>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "shadetree-ai": {
      "type": "stdio",
      "command": "shadetree-ai-mcp",
      "args": [],
      "env": {
        "SHADETREE_PORT": "<SHADETREE_PORT>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.shadetree-ai]
command = "shadetree-ai-mcp"
args = []

[mcp_servers.shadetree-ai.env]
SHADETREE_PORT = "<SHADETREE_PORT>"

Gemini CLITerminal

gemini mcp add --scope user -e SHADETREE_PORT=<SHADETREE_PORT> shadetree-ai shadetree-ai-mcp

Settings 4

`SHADETREE_PORT`	Required: Serial port of the OBD-II adapter, e.g. /dev/serial/by-id/... or a COM port; live tools fail without it.
`SHADETREE_HOME`	Optional: Folder for snapshots/ and transcripts/ (they contain the VIN); default is the current directory.
`SHADETREE_BAUD`	Optional: Adapter baud rate, default 115200.
`SHADETREE_TIMEOUT`	Optional: Seconds allowed per adapter command, default 10.

What it does

shadetree-ai connects Claude Code or Claude Desktop to a car through a USB OBD-II adapter so the assistant can pull diagnostic data and talk the owner through what it means. It reads stored, pending and (on CAN cars) permanent trouble codes, the check-engine lamp state, the freeze frame, emissions readiness monitors, Mode 06 on-board test results and the VIN, and it can sample live sensor readings such as fuel trims.

The tools fall into two groups. Nine offline tools work on scan snapshots already saved to disk, so a car does not need to be connected to review, compare or re-explain an earlier scan. Eight live tools talk to the adapter: a full scan that saves a new snapshot, single-PID reads, timed live-data polling, a fuel-trim summary, Mode 06 results, adapter identification, and a pair that start and read the project's local browser dashboard.

The read-only rule is enforced below the tools, not by instructions to the model: the transport layer accepts only OBD Modes 01, 02, 03, 05, 06, 07, 09 and 0A plus a few adapter setup commands, and no tool takes a raw command string. The server registers every built-in tool with a read-only annotation and checks at start that the tool list matches a fixed reviewed set (src/obd_reader/mcp_server.py, src/obd_reader/tools.py). The same package also ships a standalone CLI scanner and dashboard that make no AI calls.

The project's maker calls it early: the plain-words code meanings are drafted by a model and unreviewed, and the planned reference library with cited sources is not built, so Claude's explanations rest on its general knowledge.

What it needs

Runtime	Python 3.11+

An OBDLink EX USB adapter (the only one tested; OBDLink CX and cheap ELM327 clones are not supported). A 1996 or newer US OBD-II car, parked with the ignition on, for the live tools. Python 3.11 or newer and pipx (installed from the GitHub zip, not from PyPI). SHADETREE_PORT set to the adapter's serial port; on Linux the user must be in the dialout group. Claude Desktop needs the full path printed by `which shadetree-ai-mcp`.

Limits

Reads only: it cannot clear codes, write to an ECU, run actuator tests or flash modules. Not for OBD-I cars, Teslas, Mercedes or secure-gateway cars. Hardware-tested only on a 2024 Honda Ridgeline (CAN) and an early-2000s GMC truck (J1850 VPW); ISO 9141, KWP2000 and J1850 PWM are untried on real cars. live_data polls at most 8 PIDs for up to 120 s at up to 10 Hz (10 s at 2 Hz by default); Mode 06 values are raw, without unit scaling; protocols A-C (J1939, user CAN) are refused (src/obd_reader/tools.py). One tool holds the adapter at a time; live tools report busy while the dashboard samples. Code meanings are unreviewed; DTC lookup and repair playbooks are not built.

Who it suits

Suits a home mechanic or tinkerer with an OBDLink EX who wants Claude to read a check-engine light and explain the codes, freeze frame and fuel trims without any risk of the tool changing the car. The offline snapshot tools also suit reviewing saved scans away from the car. Pick something else if you need to clear codes, run bidirectional tests or code modules, use a cheap ELM327 clone or a Bluetooth/Wi-Fi dongle, or work on a non-US, OBD-I or secure-gateway vehicle. Because explanations come from the model's general knowledge rather than a service manual, treat its diagnoses as a starting point.

Tools 17

list_snapshots: Lists saved scan snapshots, oldest first.
get_snapshot: Returns one saved snapshot, the newest when no id is given.
import_snapshot: Imports a snapshot JSON file that is already inside the data folder.
read_dtcs: Gives stored, pending, permanent or all trouble codes from a snapshot.
freeze_frame: Returns the freeze frame saved with the first trouble code, if present.
readiness: Shows which emissions monitors are supported and which are incomplete.
vehicle_info: VIN, protocol, adapter voltage, ECUs and Mode 09 items from a snapshot.
list_supported_pids: Lists the Mode 01 PIDs the car supports, named where decodable.
compare_snapshots: Diffs two snapshots: codes, lamp, protocol, PIDs and readiness.
adapter_info: Identifies the connected adapter and reads its supply voltage.
scan: Runs a full read-only scan of the car and saves a snapshot.
read_pid: Reads one decodable Mode 01 PID once.
live_data: Polls up to 8 PIDs for a while and returns statistics and a series.
trim_summary: Samples short- and long-term fuel trims for both banks.
mode06_tests: Reads Mode 06 on-board monitor test results, raw values.
open_console: Starts the local token-protected dashboard and returns its link.
console_data: Reads current values and statistics from the running dashboard.

Popularity

17 popularity score

★ 25

GitHub stars	25	17 points

Measured 2026-11-07. How the score works.

Where it is published

Code	iamneilroberts/shadetree-ai ★ 25

What it can reach

Runs	On your machine
Reaches	Files on your machine, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (GitHub)
Last code change	2026-10-10

Runs entirely on your machine and talks to the car over a USB serial adapter. Car access is limited in the transport layer to OBD read modes 01, 02, 03, 05, 06, 07, 09 and 0A; other requests are refused before reaching the port, and no tool accepts a raw command. It does write local files: scan saves snapshots and every command is logged to transcripts/ under SHADETREE_HOME, and both contain the full VIN. open_console starts a web server on 127.0.0.1:8765 that needs a token in the link; it is reachable from the LAN only when started with --host 0.0.0.0 --allow-lan. The only outbound internet call is an optional NHTSA model lookup that sends a VIN key without the serial. No sign-in or API key is needed. Add-on plugins can register further tools that are not bound by the reviewed list.

Over time

GitHub stars 25 +3 (+14 %)

2522

13 Oct 20267 Nov 2026

Popularity score 17 +1 (+4 %)

1716

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![shadetree-ai on EveryMCPServer](https://everymcpserver.com/badge/shadetree-ai.svg)](https://everymcpserver.com/servers/shadetree-ai)

Connect your client

Add in one click

Or add it by command or config

Settings 4

What it does

What it needs

Limits

Who it suits

Tools 17

Similar servers

ClaudeR

LLM Checker

OpenTakeoff

World Monitor

AdLoop

Claudexor