UDS-MCP
# UDS-MCP
**An LLM-driven conformance checker for ISO 14229 (UDS) diagnostics, served over MCP.**
UDS-MCP lets an engineer who is not a UDS expert ask, in plain language, for the tests an
ECU should pass — "check that the VIN is protected", "test security access" — and get them
generated from the ECU's diagnostic database and the rules of ISO 14229, run on a bench, and
reported with a deterministic verdict per case. The same [Model Context Protocol](https://modelcontextprotocol.io)
server also exposes the UDS services as tools, so any MCP client (Claude, an IDE agent, a
custom runner) can drive a real ECU on a CAN bus or the built-in simulator.
> Status: **early development**. The UDS client, the MCP tools, the ECU simulator and the
> conformance checker for 0x10, 0x11, 0x14, 0x19, 0x22, 0x27, 0x2E, 0x31 and 0x3E (database, rules, generated test plans,
> runner and HTML report) work end to end on a virtual CAN bus — try it with no hardware.
> Hardware backends are wired but not yet validated. See the [roadmap](#roadmap) and the
> [milestone 1 design](docs/design/milestone-1-conformance.md).
---
## Why
Checking that an ECU follows ISO 14229 usually takes an expert, a commercial tool and a test
specification written by hand. UDS-MCP aims to make that accessible:
- **Ask, don't script.** The engineer describes what to verify; the LLM picks and explains the
tests. It never decides the verdict.
- **Deterministic verdicts.** Pass or fail comes from the ECU's diagnostic database and the
ISO 14229 rules (NRC tables per service, evaluation order, timing), so a run is reproducible
evidence. Every failure cites the clause it breaks.
- **Bring your own database.** Access rules (which session, which security level) come from the
ECU's database; an overlay fills the gaps of an incomplete one without editing it. Real
databases stay on the user's machine.
- **Safe by level.** The user chooses an access level (read, session, write, IO control,
flash); anything above it is skipped, and destructive cases need explicit opt-in.
- **No hardware needed to start.** The simulator answers like a conformant ECU — and the
checker is itself tested against it, including faults injected on purpose.
## Features
| Area | Status |
|---|---|
| Negative responses explained: NRC meaning per service, next step, retry policy | ✅ |
| ISO 14229 client services (0x10, 0x11, 0x14, 0x19, 0x22, 0x27, 0x2E, 0x31, 0x3E, raw) | ✅ built on [udsoncan](https://github.com/pylessard/python-udsoncan) |
| ISO 15765-2 (ISO-TP) transport over CAN / CAN FD | ✅ built on [can-isotp](https://github.com/pylessard/python-can-isotp) |
| Virtual CAN bus (no hardware, used by tests) | ✅ |
| PCAN · Intrepid neoVI / ValueCAN 4 · Vector XL · SocketCAN | 🧪 wired through python-can, not yet validated on hardware |
| MCP server (stdio) with UDS tools and a TesterPresent keep-alive | ✅ |
| MCP over HTTP (streamable) | 🧪 starts, no access control yet |
| Diagnostic database (sessions, services, DIDs, routines, access rules) from TOML, plus overlays | ✅ |
| Conformance rules (expected answer per ECU state) for 0x10, 0x11, 0x14, 0x19, 0x22, 0x27, 0x2E, 0x31, 0x3E | ✅ lenient and strict NRC order |
| Test-case generator, YAML test plans, runner (P2 on the host clock) and HTML report | ✅ on the simulator |
| Access levels, destructive-case opt-in, simulator faults the checker must catch | ✅ |
| ODX / PDX diagnostic databases via odxtools (`--odx`), with an import report and overlays | ✅ tested on our demo PDX and odxtools' example; real OEM files not yet |
| Claim / release model for shared DUT access | 🔜 planned |
| Live traffic reader with message classification | 🔜 planned |
| Software ECU simulator, configured from TOML (sessions, S3, security, DIDs, routines, DTCs, 0x78) | ✅ |
| Simulator background traffic from a CAN database (DBC via cantools, or Racelogic `.REF`) | ✅ |
| Simulator on Raspberry Pi 5 + Waveshare 2-CH CAN FD HAT (SocketCAN) | 🧪 runs via `python -m uds_mcp.sim`, not yet validated on hardware |
## Architecture
```
┌──────────────┐ MCP (stdio / HTTP) ┌───────────────────────────┐
│ MCP client │ ─────────────────────▶ │ UDS-MCP server │
│ (Claude, IDE,│ ◀───────────────────── │ • tools: session, DIDs, │
│ test runner)│ │ routines, DTCs, raw │
└──────────────┘ │ • conformance: database, │
│ rules, test plans, │
│ runner, reports │
└─────────────┬─────────────┘
│ ISO 14229 / ISO-TP
┌─────────────┴─────────────┐
│ CAN interface backend │
│ PCAN · neoVI · ValueCAN │
│ Vector · SocketCAN │
└─────────────┬─────────────┘
│ CAN / CAN FD
┌─────────┴─────────┐
│ Real ECU (DUT) │
│ or UDS simulator │
└───────────────────┘
```
## Quick start
### Requirements
- Python 3.11+
- A supported CAN interface with its vendor driver installed, **or** the simulator (no hardware needed)
### Install
```bash
git clone https://github.com/zeus-epardo/UDS-MCP.git
cd UDS-MCP
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```
### Run the simulator
The simulator answers like a real ECU, configured by the `[sim]` section of the demo ECU
[`uds_mcp/sim/demo_ecu.toml`](uds_mcp/sim/demo_ecu.toml): sessions with S3 timeout, seed/key
security access, session- and security-gated DIDs and routines, DTCs and response-pending (0x78).
`uds-mcp --interface sim` starts it in-process automatically. To run it as a standalone ECU,
for example on a Raspberry Pi with a CAN HAT:
```bash
python -m uds_mcp.sim --interface socketcan --channel can0
```
To make the bus look like a car, add `--traffic` with a CAN database (any format cantools
reads, such as DBC, or a Racelogic VBOX `.REF` file). Every message is sent periodically
(`--traffic-period-ms`, default 100) with its signals sweeping through their range, while
the simulator keeps answering UDS. It works with `uds-mcp --interface sim` too:
```bash
uds-mcp --interface sim --traffic my-car.dbc
```
Vehicle databases are third-party data: keep them out of the repository (`*.REF` and
`.reference/` are gitignored).
### Run the server
```bash
# Against the built-in simulator (no hardware)
uds-mcp --interface sim
# Against a real ECU through PCAN, with your own ECU config
uds-mcp --interface pcan --channel PCAN_USBBUS1 --config config/my-ecu.local.toml
```
The server speaks MCP over stdio (default) or streamable HTTP (`--transport http`).
While the ECU is outside the default session, it sends TesterPresent (0x3E 80) in the
background so the session survives the pauses of a person or an LLM.
To see a full scripted session (read VIN, extended session, security access, write,
routine, DTCs) without any MCP client installed:
```bash
python examples/demo_client.py
```
### Connect an MCP client
Claude Code:
```bash
claude mcp add uds -- uds-mcp --interface sim
```
Claude Desktop (`claude_desktop_config.json`, use the full path to `uds-mcp` from your venv):
```json
{
"mcpServers": {
"uds": {
"command": "uds-mcp",
"args": ["--interface", "sim"]
}
}
}
```
Then, from the client:
```
open an extended session, unlock security level 1 and change the VIN to UDSMCP12345678901
```
## MCP tools
IDs and payloads are hex strings (`"F190"`, `"0xF190"`, `"22 F1 90"`). Every UDS tool returns
the same JSON shape: `{service, ok, request, response, data}`, plus `error` for local or
transport problems. A negative response is a normal result that explains itself, so the
agent can decide what to do next:
```json
{"service": "WriteDataByIdentifier", "ok": false, "request": "2E F1 90 55 44 ...",
"response": "7F 2E 31", "nrc": "0x31", "nrc_name": "RequestOutOfRange",
"nrc_meaning": "The DID is unknown, read-only, not writable in the active session, or the value is invalid.",
"next_step": "Check the identifier, the value and the active session.", "retry": "no"}
```
| Tool | Description | Status |
|---|---|---|
| `get_ecu_info` | ECU addresses, current session, known DIDs, routines, security levels | ✅ |
| `diagnostic_session_control` | 0x10 — `default`, `programming`, `extended`, `safety` or a number | ✅ |
| `ecu_reset` | 0x11 — `hard`, `key_off_on`, `soft` or a number | ✅ |
| `read_data_by_identifier` | 0x22 — one or more DIDs, decoded by the ECU config | ✅ |
| `write_data_by_identifier` | 0x2E — value as hex or ASCII | ✅ |
| `security_access` | 0x27 — seed/key with the key algorithm configured for the level | ✅ |
| `routine_control` | 0x31 — `start` / `stop` / `results` | ✅ |
| `read_dtc_information` | 0x19 02 — DTCs by status mask | ✅ |
| `clear_diagnostic_information` | 0x14 | ✅ |
| `tester_present` | 0x3E (a background keep-alive already runs) | ✅ |
| `send_raw` | Any UDS request as hex, raw response back (handles 0x78) | ✅ |
| `claim_dut` / `release_dut` | Acquire or release exclusive write access to the DUT | 🔜 |
| `read_traffic` | Stream classified bus traffic (diagnostic / non-diagnostic / unknown) | 🔜 |
| `describe_database` | Expected sessions, services, DIDs and routines with their access rules | ✅ |
| `generate_test_plan` | ISO 14229 conformance cases for 0x10/0x11/0x14/0x19/0x22/0x27/0x2E/0x31/0x3E as a YAML plan | ✅ |
| `run_test_plan` | Run a plan; verdicts, CAN trace (BLF) and HTML report | ✅ |
| `explain_result` | One case in detail: sent, received, expected, reference, NRC meaning | ✅ |
## Project layout
```
uds_mcp/
├── core/ # ISO 14229 client (udsoncan + can-isotp), NRC table, results
├── diagdb/ # Diagnostic database: expected sessions, services, DIDs, access rules
├── conformance/ # Rules (the oracle) and, next, the test-case generator
├── candb/ # CAN signal databases: cantools formats plus a Racelogic .REF reader
├── interfaces/ # CAN backends through python-can (pcan, neoVI, vector, socketcan, sim)
├── server/ # MCP server and tools
└── sim/ # ECU simulator and background traffic (host and Raspberry Pi)
tests/
docs/
```
## Roadmap
1. **Milestone 1 — conformance on the simulator.** Test-case generator for 0x10, 0x22, 0x27 and
0x2E (positive, session and security gating, length, sequence, lockout, timing), YAML test
plans, a runner that records the CAN trace and measures P2 from frame timestamps, an HTML
report, access levels, and simulator faults that prove the checker catches them.
[Design](docs/design/milestone-1-conformance.md).
2. ~~Milestone 1.5 — ODX / PDX databases~~ done: `uds-mcp --odx my-ecu.pdx --overlay keys.toml`.
3. ~~More services~~ done for 0x11, 0x14, 0x19 (status-mask and no-parameter reports), 0x31 and
0x3E. Next: strict NRC order once each service's evaluation order is verified against the
standard.
4. **Bench hardware** — Raspberry Pi 5 + Waveshare 2-CH CAN FD HAT (MCP2518FD, SocketCAN), then
PCAN, neoVI / ValueCAN 4 and Vector XL against real ECUs.
5. **Later** — claim/release for shared benches over HTTP, live traffic classification, Excel
and MDF4 exports, DoIP.
## Scope and disclaimer
UDS-MCP is a conformance *checker*, not a certification: it does not replace an accredited
test specification. It implements publicly available standards (ISO 14229, ISO 15765) and contains **no proprietary OEM or supplier data**: no vendor-specific DIDs, routines, security algorithms, ECU configurations or test results. Everything specific to a given vehicle program must be supplied by the user through configuration files that are not part of this repository.
Use at your own risk. Writing to or reprogramming an ECU can brick it. Always test against the simulator first.
## Contributing
Issues and pull requests are welcome. Please open an issue before large changes so we can agree on the design. Run `ruff` and `pytest` before submitting.
## License
MIT — see [LICENSE](LICENSE).
## Credits
UDS-MCP is created by **[Zeus Epardo](https://github.com/zeus-epardo)** and co-created with
**[Claude](https://www.anthropic.com/claude)** (Anthropic) through Claude Code: design,
implementation and docs are built together, and Claude's commits carry a `Co-Authored-By` trailer.
Built on the shoulders of [python-can](https://github.com/hardbyte/python-can),
[can-isotp](https://github.com/pylessard/python-can-isotp),
[udsoncan](https://github.com/pylessard/python-udsoncan) and the
[Model Context Protocol](https://modelcontextprotocol.io) SDK.
TDQS
Scored across 11 tools
Each tool maps to a distinct UDS diagnostic service or utility, so an agent can readily choose between session control, reset, DID read/write, security access, routines, DTCs, and tester present. send_raw overlaps by design as an explicit fallback for services without a dedicated tool, but its purpose is clearly stated and does not make the specialized tools ambiguous.
All tool names use consistent snake_case and largely mirror standard UDS service terminology, making the set readable and predictable. However, several names are noun phrases rather than strict verb_noun forms (e.g. security_access, routine_control, tester_present), so the pattern is slightly mixed.
Eleven tools is well-scoped for a UDS diagnostic server: the set covers the core services agents commonly need without becoming unwieldy. Each dedicated tool has a clear role, and send_raw prevents the need to add many rarely used service-specific tools.
The server covers the main diagnostic lifecycle: session control, reset, DID read/write, security access, routines, DTC read/clear, tester present, and raw requests. Some UDS service areas such as IO control, memory transfer/download, or extended DTC snapshot reads lack dedicated tools, but send_raw provides a practical fallback.