---

Why this exists

Finding the one CAN frame that controls your blinker — or your steering angle, or your door locks — is a slow, fiddly loop: log traffic, do the thing, log again, diff bytes by hand, guess the CRC, replay it, repeat. Every step lives in a different script.

panda-mcp collapses that loop into a conversation. You tell Claude "record the bus, I'll flip the blinker, now find what changed" and it drives the Panda, runs comma.ai's own diff heuristics, cracks the CRC, and replays the candidate frame — all through 26 typed MCP tools.

And because it ships with a full mock CAN bus, you can learn the entire workflow on your laptop on the train home, with no Panda and no car.

You:    Connect in mock mode, record a baseline, then record again — I'll toggle the blinker.
Claude: [device_connect → capture_start → capture_stop ×2]
You:    Which bits only showed up while blinking?
Claude: [analyze_diff_new_bits] → 0xE1, byte 0 bit 0 flipped 0→1. That's your blinker.
You:    Prove it. Send it back.
Claude: [device_set_safety_mode('alloutput') → send_frame 0xE1 ...] → sent 20×. 🚗💡

✨ Features

• 🎙️ Background capture — non-blocking recording with bus / arbitration-ID / duration / frame-count filters
• 🔍 Two diff engines, straight from comma.ai — can_bit_transition (clean 0→1/1→0 flips across a split) and can_unique (bits that appear only against a baseline)
• 🎯 Signal hunting — pin a known number (speed, RPM, steering angle) to an exact ID + byte offset + endianness
• 📸 Snapshots — freeze the bus state before/after an action and XOR-diff it
• 📤 Transmit & fuzz — single frame, bulk, single-byte sweep, or full timed replay of a recording
• 🧮 CRC toolkit — a catalogue of real automotive CRCs (J1850, AUTOSAR, CCITT…), brute-force identification with per-message magic-init sweep, and automatic CRC-field detection across a whole capture
• 🧪 Mock mode — a deterministic synthetic bus that exercises every tool, so dev & tests need zero hardware
• 🔒 Safe by default — listen-only until you explicitly unlock transmission
• 💾 Interop — export to candump .log for Cabana / SavvyCAN / can-utils

📑 Table of contents

• Quickstart
• Mock mode
• How it works
• Tool reference
• Workflows
• Sending frames vs. flashing firmware
• Safety
• Development
• Roadmap
• Credits & license

🚀 Quickstart

git clone https://github.com/<you>/panda-mcp.git
cd panda-mcp

py -m venv .venv
.venv/Scripts/python -m pip install -e .            # mock mode only
.venv/Scripts/python -m pip install -e ".[panda]"   # + real hardware (pandacan)

Register the server with Claude Code by pointing it at the bundled claude.json:

{
  "mcpServers": {
    "panda": {
      "command": ".venv/Scripts/python.exe",
      "args": ["-m", "panda_mcp.server"],
      "env": { "PYTHONPATH": "src" }
    }
  }
}

Then just ask Claude to device_connect(mock=true) and start exploring.

🧪 Mock mode

No Panda? No car? No problem. device_connect(mock=true) spins up a deterministic synthetic CAN stream designed to make every analysis tool light up:

Arb ID	Rate	Payload	Demonstrates
0x1A0	20 Hz	rolling counter nibble + J1850 CRC8 over bytes 0–6	crc_detect_field, crc_brute_force
0x2B0	10 Hz	static DEADBEEF…	baseline noise for diffs
0x3C0	50 Hz	int16 "steering angle" sweeping via sin(t)	analyze_find_value
0x0E1	1 Hz	one toggle bit driven by a virtual "blinker"	analyze_diff_transition

Everything you learn in mock mode maps 1:1 onto real hardware — only the mock=true flag changes.

🛠 How it works

┌──────────────┐   MCP tools    ┌─────────────────────────────────────────┐
│    Claude    │ ─────────────► │             panda_mcp.server            │
│  (you, chat) │ ◄───────────── │            FastMCP · 26 tools           │
└──────────────┘    results     └───────────────────┬─────────────────────┘
                                                     │
        ┌────────────────────────┬───────────────────┼────────────────────┐
        ▼                        ▼                    ▼                    ▼
 ┌────────────┐          ┌──────────────┐     ┌──────────────┐     ┌────────────┐
 │  device.py │          │  session.py  │     │ analysis.py  │     │   crc.py   │
 │ Panda  +   │          │ bg-threaded  │     │ bit-state    │     │ automotive │
 │ MockPanda  │          │ capture store│     │ diff engines │     │ CRC engine │
 └─────┬──────┘          └──────────────┘     └──────────────┘     └────────────┘
       │ USB
       ▼
 ┌────────────┐
 │ Panda Red  │  STM32H725 · CAN/CAN-FD
 │  🚗 car    │
 └────────────┘

Module	Responsibility
server.py	FastMCP entry point — all 26 tools, argument parsing, safety gating
device.py	Panda abstraction + MockPanda synthetic stream + safety-mode constants
session.py	Background-threaded capture store and snapshots (all in-memory)
analysis.py	Bit-state tracking, the two diff engines, find_value, per-ID stats
crc.py	CRC catalogue, brute-force identification, CRC-field detection
model.py	The CanFrame dataclass

📖 Tool reference

Group	Tool	What it does
Device	device_connect	Connect to a Panda (or mock=true)
	device_status	Connection, firmware, safety mode, bus errors
	device_set_safety_mode	silent (listen-only) / alloutput (unlock TX)
	device_set_can_speed	Set a bus bitrate in kbps
	device_flash	Flash stock or custom firmware
	device_recover	DFU recovery for a bricked device
Capture	capture_start	Begin recording (bus/ID/duration/count filters)
	capture_stop	Stop and summarize
	capture_list	List all captures
	capture_get	Page through raw frames
	capture_delete	Discard a capture
Analyze	analyze_stats	Per-ID count, period, length, dynamic bytes
	analyze_diff_transition	Clean bit flips before/after a split time
	analyze_diff_new_bits	Bits unique to a capture vs. baselines
	analyze_find_value	Locate a number → ID + offset + endianness
Snapshot	snapshot_take	Freeze latest payload per (bus, ID)
	snapshot_diff	XOR-diff two snapshots
Send	send_frame	Transmit one frame (optionally repeated)
	send_bulk	Transmit many frames at once
	send_fuzz	Sweep one byte across a range
	send_replay	Replay a capture with original timing
CRC	crc_compute	Compute a catalogued CRC over hex data
	crc_list	List CRC algorithms + parameters
	crc_brute_force	Identify the algorithm (with init sweep)
	crc_detect_field	Find the CRC byte + algo across a capture
Export	export_candump	Write a candump .log (Cabana/SavvyCAN)

🧭 Workflows

Hunt down a control frame (the blinker)

device_connect(mock=true)

capture_start()                  → cap-aaaa          # baseline: do nothing
capture_stop(cap-aaaa)

capture_start()                  → cap-bbbb          # now toggle the blinker
capture_stop(cap-bbbb)

analyze_diff_new_bits(cap-bbbb, [cap-aaaa])          # bits unique to "blinking"
# …or, if you toggled mid-capture:
analyze_diff_transition(cap-bbbb, split_ts=5.0)

device_set_safety_mode('alloutput')
send_frame(arb_id='0xE1', data='01000000000000', bus=0, count=20, interval_ms=50)

Pin a numeric signal (speed / RPM / steering)

analyze_find_value(cap-xxxx, value=2000, bit_length=16)
# → 0x3C0, byte_offset 0, little-endian, 14 matches

Crack a CRC

crc_detect_field(cap-xxxx, arb_id='0x1A0')
# → crc_index 7, confirmed: crc8_sae_j1850 (init 0xFF) across 30 frames ✅

crc_brute_force(frame='10123456780000CC')            # single-frame identification
crc_compute(data='10123456780000', algorithm='crc8_sae_j1850')

⚡ Sending frames vs. flashing firmware

You do not need custom firmware to send frames. Transmission is unlocked in software via the safety mode:

device_set_safety_mode('alloutput')

device_flash / device_recover exist only for firmware updates, custom on-device safety logic, or un-bricking:

• device_flash() — build & flash the stock firmware (the Panda's own flash())
• device_flash('/path/fw.bin') — flash a custom binary
• device_recover() — DFU recovery for an unresponsive device

The Panda Red is an STM32H725; flashing runs over USB DFU (VID 0x0483, PID 0xdf11). The device reboots afterward — call device_connect again.

🔒 Safety

[!WARNING] Injecting frames onto a moving vehicle's powertrain bus can disable brakes, steering, or throttle. People can get hurt.

• The server boots listen-only (silent). Transmission requires an explicit device_set_safety_mode('alloutput') — there is no way to send by accident.
• Only unlock output on a bench harness or a vehicle you own and have immobilized.
• This project is for education, research, and tinkering on hardware you control. You are responsible for how you use it.

🧰 Development

.venv/Scripts/python -m pytest -q        # 7 hardware-free end-to-end tests

The whole test suite runs against MockPanda — capture, both diff engines, find_value, CRC detection, the safety gate, and replay — so CI never needs a device.

src/panda_mcp/
  server.py     FastMCP entry point · all 26 tools
  device.py     Panda abstraction + MockPanda synthetic stream
  session.py    background-threaded capture store + snapshots
  analysis.py   bit-state diffing + find_value + per-ID stats
  crc.py        automotive CRC catalogue + brute force + field detection
  model.py      CanFrame
tests/
  test_smoke.py hardware-free end-to-end tests

🗺 Roadmap

• DBC decoding via cantools — decode/encode against a .dbc
• Persistence — auto-save captures to disk, reload .candump/CSV as sessions
• CAN-FD — widen bit arrays to 64-byte payloads
• Multi-message CRC counters — auto-derive counter + checksum pairs
• SavvyCAN/Cabana import alongside the existing export

Contributions welcome — open an issue or PR. If you add a tool, add a mock signal that exercises it so the test suite stays hardware-free.

🙏 Credits & license

The two diff engines are faithful ports of comma.ai's own examples — can_bit_transition.py and can_unique.py. Hardware access is via the pandacan library. Huge thanks to comma.ai for open-sourcing the Panda.

Released under the MIT License — same as panda.