CANarchy MCP server
Commit 27. Okt. 2026Ermöglicht es AI Agents, CAN- und J1939-Busverkehr über strukturierte, maschinenlesbare Event-Streams zu erfassen, zu dekodieren und zu manipulieren.
Auch bekannt als hexsecs/canarchy
- Stars
- 5
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 27. Okt. 2026
- Lizenz
- GPL-3.0
Was ist CANarchy MCP?
Ermöglicht es AI Agents, CAN- und J1939-Busverkehr über strukturierte, maschinenlesbare Event-Streams zu erfassen, zu dekodieren und zu manipulieren.
Zusammenfassung generiert aus dem README des Projekts
Über CANarchy MCP server
Security-Forscher und Ingenieure für Nutzfahrzeuge können CAN- und J1939-Busverkehr mithilfe eines Stream-First-Toolkits erfassen, dekodieren und manipulieren. Das System ist auf Automatisierung ausgelegt und behandelt jeden Command-Output als typisierten, maschinenlesbaren Event-Stream in den Formaten JSON, JSONL oder Text. Dies ermöglicht es Nutzern, Daten direkt in Skripte zu pipen oder sie AI Agents über einen integrierten MCP server zu übergeben.
Nutzer können über ein Command-Line Interface oder ein Full-Screen TUI mit dem Bus interagieren, um den Verkehr, Signale und DM1-Fehler live zu überwachen. Das Toolkit unterstützt verschiedene Transport-Backends via python-can, einschließlich socketcan, virtuelle Busse und UDP Multicast. Für Tests ohne Hardware steht ein deterministisches Scaffold-Backend zum Streamen von Events zur Verfügung.
Spezialisierte Workflows umfassen die J1939 PGN- und SPN-Dekodierung, UDS-Diagnosedienste sowie Reverse-Engineering-Tools zum Ranking von Signalen oder zur Anomalieerkennung. Active-Transmit-Funktionen wie Fuzzing und Frame-Generierung sind durch ein Sicherheitsmodell geschützt, das eine explizite Bestätigung oder einen Dry-Run-Modus erfordert, um unbeabsichtigte Bus-Interferenzen zu vermeiden.
Was du damit machen kannst
- 1Security Anomaly DetectionForscher können zwei Captures vergleichen, um Timing-Drifts oder den Zusammenbruch der Payload-Entropie zu identifizieren.
- 2Protocol Reverse EngineeringEntwickler können wahrscheinliche Signale und Counter aus einem unbekannten Bus-Capture ranken.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
Konfiguration
CANARCHY_TRANSPORT_BACKEND
| Name | Beschreibung | Typ |
|---|---|---|
| CANARCHY_TRANSPORT_BACKEND | — |
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Noch nicht verifiziert. Ein Server benötigt einen Score von 80, keine kritischen Befunde und genug Daten für unsere Prüfung. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarhexsecs/canarchy is public and reachablegithub.com/hexsecs/canarchy ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)Nicht geprüft
- Open Source Lizenz (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Bestanden
- Commit oder Release im letzten JahrLast commit or release 2026-10-27github.com/hexsecs/canarchy ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNicht geprüft
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
- Keine versteckten Anweisungen an das Modell0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNicht geprüft
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenWhat is CANarchy?
CANarchy is a CLI-first runtime for capturing, decoding, and manipulating CAN and CAN-FD traffic. Most CAN tools force a tradeoff: interactive but hard to automate, scriptable but too raw, or protocol-aware but inconsistent across interfaces. CANarchy is built around the opposite constraint — every output is a stream of typed events (--json, --jsonl, --text) you can parse, pipe, or forward to an LLM agent over MCP.
It's for you if you're:
- A security researcher reversing an unknown bus, fuzzing ECUs, or diffing captures for anomalies.
- A heavy-vehicle / J1939 engineer who wants PGN/SPN decoding, TP reassembly, and DM1 fault parsing without dropping to raw IDs.
- Building automation or AI agents that need a stable, machine-readable CAN interface instead of scraping human-formatted text.
Install
pipx install canarchy # isolated, on PATH everywhere
# or: pip install --user canarchy
Requires Python 3.11+. Live transport uses python-can (socketcan, virtual bus, UDP multicast, and more).
Try it in 60 seconds — no hardware required
canarchy --version
canarchy doctor --text # 8 offline health checks; all green = good install
# Stream typed events from the deterministic scaffold backend —
# no hardware, no fixtures, no network. This is the JSONL contract:
CANARCHY_TRANSPORT_BACKEND=scaffold canarchy capture can0 --jsonl
Point it at a real interface once you have one:
canarchy capture can0 --candump # human-friendly live view
canarchy capture can0 --jsonl | jq . # typed events, one per line
Prefer to explore visually? Launch the full-screen TUI (pictured above) and watch the bus live:
canarchy tui # /capture <iface> to stream; /filter, /sort, /help
Why CANarchy?
The event schema is the stable contract; the CLI wraps it. That one design choice is what sets CANarchy apart from most open-source CAN tooling:
- Structured output is the contract, not an afterthought. Every command — capture, decode, fuzz, reverse-engineer — emits the same canonical JSON envelope. Parse once, reuse everywhere.
- Pipe-first.
--jsonlstreams one typed event per line, so| jq,| grep, or a downstream script Just Works. - J1939 is first-class. PGN decoding, SPN extraction, TP session reassembly, and DM1 fault parsing resolve names from a bundled SAE catalog — not just raw arbitration IDs.
- Agent-ready. A built-in MCP server exposes the toolkit to Claude and other MCP clients, so an agent can drive CAN analysis directly.
| CANarchy | Typical CAN CLI tools | |
|---|---|---|
| Structured output as a core contract | ✅ | ✗ / partial |
| Pipe-friendly typed event stream | ✅ | partial |
| Provider-backed DBC discovery & cache | ✅ | ✗ |
| J1939-first operator workflows | ✅ | partial |
| MCP / agent integration | ✅ | ✗ |
See the full CAN tool feature matrix for an honest, side-by-side comparison with can-utils, SavvyCAN, Caring Caribou, TruckDevil, and others.
What can you do with it?
# Decode a capture against a DBC
canarchy decode --file trace.candump --dbc vehicle.dbc --jsonl
# J1939 heavy-vehicle analysis
canarchy j1939 decode --file trace.candump --text
canarchy j1939 spn 110 --file trace.candump --text # Engine Coolant Temp
canarchy j1939 dm1 --file trace.candump --text # active fault codes
# Reverse-engineer an unknown bus: rank likely signals, counters, anomalies
canarchy re signals --file trace.candump --jsonl
canarchy re anomalies --file trace.candump --baseline known_good.candump --jsonl
# Diff two captures per arbitration ID (rate/timing/entropy deltas)
canarchy compare before.candump after.candump --json
# Active workflows (gated by the active-transmit safety model; --dry-run plans safely)
canarchy generate can0 --count 10 --gap 50 --id 7DF --jsonl
canarchy replay --file trace.candump --rate 2.0 --json
# Pipe events straight into downstream tooling
canarchy j1939 spn 110 --file trace.candump --jsonl \
| jq '[.payload.value, .payload.units, .payload.timestamp]'
Drive it from an AI agent (MCP)
CANarchy ships a Model Context Protocol server, so an LLM agent can capture, decode, and analyze CAN traffic through the same structured contract the CLI uses.
canarchy mcp install --client claude-desktop # or: --client claude-code
canarchy mcp serve # or run the stdio server directly
Active-transmit tools require an explicit acknowledgement, so an agent can't put frames on a live bus by accident. See the active-transmit safety design.
The full-screen TUI
canarchy tui opens an interactive, full-screen dashboard that streams the bus live:
- Responsive workspaces:
Alt+1–Alt+5switch Traffic, Signals (one row per decoded observation), J1939, UDS, and Findings. Traffic opens as a per-bus, standard/extended-ID summary with counts, rate, changed-byte offsets, and activity;vswitches to the chronological event log. The active table uses the available height; wide terminals show a selected-row inspector, whileEnteropens complete raw hex/bit details on narrow terminals (Escreturns). - Background capture:
/capture <iface>starts streaming;/stop(orx) ends it. - Interactive:
/filter traffic 'id==0x123'(alsopgn==andsa==),/sort traffic <column>, arrow-key row navigation,F4to freeze inspection or return live,F3to expand activity,spaceto pause the feed,[/]to resize the backlog,ctrl+fto maximize a table. Other panes keep/filter <pane> <text>and/sort <pane> <column>. - Type any real CANarchy command at the prompt — event output folds into the panes, while stats, DBC inspection, diagnostics, reference lookups, errors, and help appear in a scrollable result view. Press
F2to switch views orEscto return to the panes.
Fully implemented and tested:
Transport
capture,send,filter,stats— transport workflows with livepython-canand deterministic scaffold backends;statsreports per-ID frequency/timing, DLC distribution, and a bus-load estimatecompare— diff two or more plain CAN captures per arbitration ID and identifier type (standard/extended): frame-count/rate deltas, cycle-time drift, payload-entropy deltas against a baseline, each identifier flagged (rate-drop, rate-spike, entropy-collapse, timing-drift, new/dropped)capture-info— fast capture metadata without loading every framegenerate— cangen-style frame generation (fixed, random, incrementing)simulate— deterministic, profile-driven mix of classic CAN, J1939, and DM1 traffic (no hardware)gateway— bridge frames between two interfaces (uni- and bidirectional)replay,sequence replay— deterministic replay planning from candump files, and YAML/JSON multi-message coordinated transmit
Databases (DBC / ARXML / KCD / SYM via cantools)
decode,encode— database-backed signal decode/encode;encoderesolves SAE PGN/SPN display names for round-tripsdbc inspect(incl.--layout,--search),dbc signals— database and signal inspectiondbc convert— convert databases between DBC / KCD / SYMdbc generate-c— C source/header/fuzzer generation from a databasedbc provider list,dbc search,dbc fetch,dbc cache list|prune|refresh— provider-backed DBC discovery and cache workflows
J1939
j1939 monitor,decode,pgn,spn,tp,dm1,faults,summary,inventory,compare,map— operator workflows across live, file-backed, and decoded views; faults resolve SPN names and FMI descriptions from the bundled SAE catalog
UDS
uds scan,trace,services,subservices,ecu-reset,tester-present,security-seed,dump-dids,read-memory,auto— diagnostic discovery and active workflows
Reverse engineering
re signals,re counters,re entropy— file-backed candidate ranking, annotated with J1939 PGN/source-address context, transport-protocol awarere correlate— correlate candidate fields against timestamped reference seriesre anomalies— inter-frame-timing and unexpected/dropped-ID anomaly detection; against a baseline it also flags per-ID rate drop/spike (suppression/injection) and payload-entropy collapse (plateau/frozen-value attacks)re corpus— cross-capture coverage, cycle-time drift, and signal-stability analysisre match-dbc,re shortlist-dbc— provider-backed DBC candidate ranking against captures
Datasets
datasets provider list,search,inspect,fetch,download,cache list|refresh— public CAN dataset provider workflowsdatasets convert,stream,replay— dataset conversion and bounded streaming/replay
Diagnostics over other transports
doip discovery,services,ecu-reset,tester-present,security-seed,dump-dids— DoIP UDP discovery and active diagnostic workflowsxcp scan,info,dump— XCP slave discovery, capability interrogation, and bounded memory dump
Visualization, front ends, and extensions
plot— signal time-series plots to PNG/SVG/HTML (pip install canarchy[plot])web serve— read-only browser dashboard over the JSONL envelope (HTTP + WebSocket)shell— interactive REPL and--commandscripting modetui— full-screen terminal dashboard with background live captureplugins list|info|enable|disable— Python entry-point plugin discovery and togglesskills provider list,search,fetch,cache list|refresh— repository-backed CANarchy skill discovery, caching, and provenance
Active-transmit fuzzing (gated by the active-transmit safety design; --dry-run is the safe planning path)
fuzz payload,fuzz replay,fuzz arbitration-id,fuzz identify— payload/replay/ID-walk fuzzing and bisecting a fuzz log to the culprit framefuzz signal,fuzz spn— DBC-signal and J1939-SPN-aware mutation with sentinel coveragefuzz guided— response-feedback coverage-guided fuzzing with a persisted seed corpus and independent, incremental payload/response evidence archives
Session, export, and utilities
session save,load,show,verify,annotate,attach,bundle,import— research records with input provenanceexport— structured artifact exportdoctor— local environment health checks (Python,python-can, vendor backends, caches, MCP, config)mcp serve,mcp install— Model Context Protocol server and client-config helpercompletion {bash,zsh,fish}— emit a shell completion script--log-level,--quiet— global stderr logging controls (place before the subcommand)
Default transport backend is python-can; set CANARCHY_TRANSPORT_BACKEND=scaffold for deterministic offline behavior.
The structured contract
Every successful command returns a stable envelope:
{ "ok": true, "command": "capture", "data": {}, "warnings": [], "errors": [] }
Failures return structured errors with actionable hints (and a documented error-code catalog):
{
"ok": false,
"command": "decode",
"data": {},
"warnings": [],
"errors": [
{ "code": "DBC_LOAD_FAILED", "message": "Failed to parse DBC file.", "hint": "Validate the DBC syntax and line endings." }
]
}
Use --candump for a human-oriented live view; use --jsonl when feeding scripts or agents — every line is a typed event from the canonical schema. Set CANARCHY_PYTHON_CAN_INTERFACE to choose an interface type, or CANARCHY_TRANSPORT_BACKEND=scaffold for deterministic offline behavior.
Documentation
- Getting Started · Cookbook — task-oriented recipes
- Event Schema — the canonical envelope for all structured output
- Command spec · Architecture
- CAN Tool Feature Matrix — comparison to other OSS CAN tools
- J1939 Heavy Vehicle Demo · Troubleshooting
- Full docs site: hexsecs.github.io/canarchy
Install from source (development)
CANarchy uses uv for environment, dependency, and packaging workflows.
git clone https://github.com/hexsecs/canarchy && cd canarchy
uv sync # create the venv and install from the checkout
uv run canarchy --help
uv tool install --editable . # optional: put `canarchy` on your PATH; edits take effect live
Run the test suite end to end:
uv run python -m unittest discover -s tests -v
Shell completions for bash, zsh, and fish come from canarchy completion <shell> — see Getting Started.
Community & contributing
CANarchy is GPL-3.0-licensed and welcomes contributions.
- ⭐ Star the repo if it's useful — it genuinely helps others find it.
- Contributing guide — local development, branch flow, and PR gates
- Code of Conduct
- Security Policy — reporting concerns and safe active-bus operation
⚠️ CANarchy can transmit on live buses. Only operate against vehicles, ECUs, and networks you own or are explicitly authorized to test. Active-transmit commands require explicit acknowledgement by design.
Philosophy
- The CLI is the contract.
- Protocol semantics over raw frames.
- Structured output over formatted text.
- Reproducible workflows over ad-hoc interaction.
Versioning follows SemVer; see the changelog and release workflow. src/canarchy/__init__.py is the authoritative version source.
CANarchy MCP Fragen
Kann ich CANarchy ohne Hardware nutzen?
Ja, du kannst das deterministische Scaffold-Backend verwenden, um typisierte Events ohne Hardware oder Netzwerk-Fixtures zu streamen.
Gibt es einen Sicherheitsmechanismus für das Senden von CAN-Frames?
Ja, Active-Transmit-Tools sind durch ein Sicherheitsdesign geschützt, das eine explizite Bestätigung erfordert, um versehentliches Frame-Injection auf einem Live-Bus zu verhindern.