Skip to main content
Glama

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 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 and the milestone 1 design.


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.

Related MCP server: py-canoe

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

ISO 15765-2 (ISO-TP) transport over CAN / CAN FD

✅ built on 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

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: 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:

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:

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

# 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:

python examples/demo_client.py

Connect an MCP client

Claude Code:

claude mcp add uds -- uds-mcp --interface sim

Claude Desktop (claude_desktop_config.json, use the full path to uds-mcp from your venv):

{
  "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:

{"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.

  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.

Credits

UDS-MCP is created by Zeus Epardo and co-created with 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, can-isotp, udsoncan and the Model Context Protocol SDK.

Available Tools

11 tools
clear_diagnostic_informationA

0x14 ClearDiagnosticInformation for a DTC group (FFFFFF = all). Confirm with the user before clearing.

Inputs: group. Returns: object

diagnostic_session_controlC

0x10 DiagnosticSessionControl. session: default, programming, extended, safety or a hex number.

Inputs: session. Returns: object

ecu_resetA

0x11 ECUReset. reset_type: hard, key_off_on, soft or a hex number. Returns the ECU to the default session. Confirm with the user before resetting.

Inputs: reset_type. Returns: object

get_ecu_infoA

Describe the connected ECU: interface, CAN IDs, current session, known DIDs, routines and configured security levels.

Inputs: no named parameters. Returns: object

read_data_by_identifierB

0x22 ReadDataByIdentifier. dids: list of hex DIDs, e.g. ["F190", "F18C"]. DIDs not known to the ECU config must be read one at a time.

Inputs: dids (required). Returns: object

read_dtc_informationC

0x19 02 ReadDTCInformation: DTCs whose status matches status_mask (hex byte).

Inputs: status_mask. Returns: object

routine_controlC

0x31 RoutineControl on a hex routine_id, e.g. "0203". Routines act on the ECU: confirm with the user before starting one.

Inputs: routine_id (required), control, data_hex. Returns: object

security_accessB

0x27 SecurityAccess: request a seed for odd level and send the key computed by the key algorithm configured for that level. Needs a non-default session.

Inputs: level. Returns: object

send_rawA

Send any UDS request as hex bytes, e.g. "22 F1 90", and get the raw response. Use it for services without a dedicated tool.

Inputs: request_hex (required). Returns: object

tester_presentA

0x3E TesterPresent. Rarely needed: a keep-alive already runs in the background.

Inputs: no named parameters. Returns: object

write_data_by_identifierA

0x2E WriteDataByIdentifier. Give the value as value_hex ("00 64") or value_ascii (text). Usually needs the extended session and security access. Confirm with the user before writing.

Inputs: did (required), value_hex, value_ascii. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A local-first, read-only MCP server for vehicle diagnostics that exposes structured OBD-II tools for reading PIDs, DTCs, and ECU snapshots without raw protocol access.
      7
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that drives Keil µVision debug sessions for 8051/C51 targets via the native UVSOCK/UVSC interface: build, run control, breakpoints, and read/write of variables, memory & expressions (22 tools). Works with the Keil Simulator (no hardware needed) or GLink+/ULINK on real targets.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes 20 vehicle-security tools to AI coding agents such as Claude Code and Cursor, enabling them to send, fuzz, and analyze CAN frames, run UDS diagnostics and seed-key handshakes, simulate DoIP ECUs, and decode ISO-TP, J1939, DBC, and V2X data. Everything runs against a virtual CAN bus, so no vehicle or hardware is required.
      1
      MIT