OBD-II MCP Server
This server lets an AI client read and manage OBD-II vehicle diagnostics through a local ELM327 Bluetooth adapter or simulated vehicle data.
Check ELM327/ECU connection status, serial port, and negotiated OBD-II protocol.
List live sensor PIDs supported by the connected vehicle.
Read one or more supported sensors, such as RPM, speed, coolant temperature, and intake pressure, with units.
Read stored and pending/current-cycle DTCs with known technical descriptions without modifying the ECU.
Clear DTCs and freeze-frame data only with explicit
confirm: true; this may reset readiness monitors and temporarily affect MIL state.Get vehicle info including VIN when supported, MIL/check-engine status, DTC count, and protocol.
Run in simulation mode with generated data for the same six tools, where clearing DTCs updates simulator state until restart.
Expose six tools to MCP clients over stdio or Streamable HTTP, serializing COM-port access and reconnecting after communication failures.
Connects to a paired classic Bluetooth ELM327 adapter over Serial Port Profile (SPP) to read OBD-II vehicle diagnostics, including supported sensors, DTCs, VIN, MIL status, and protocol information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OBD-II MCP Server What diagnostic trouble codes are stored?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OBD-II MCP Server
A local Python MCP server that lets an AI client read OBD-II diagnostics from a vehicle through a paired ELM327 Bluetooth adapter. It can also run in simulation mode with generated vehicle data, without an adapter or vehicle.
Documentation
Architecture and concepts — components, request flows, concurrency, reconnection, simulation, error model, and analogies for the non-obvious logic.
Public Python modules, classes, and functions include PEP 257-style docstrings describing their contracts and side effects.
Related MCP server: connected-vehicle-health
What it does
The server exposes six MCP tools:
get_connection_status— ELM327/ECU status, serial port, and negotiated protocol.list_supported_sensors— the live PIDs supported by the connected vehicle.read_sensor— one or more supported sensor values with units.read_dtc— stored and pending/current-cycle DTCs.clear_dtc— clears DTCs only when called withconfirm: true.get_vehicle_info— VIN (when supported), MIL status, DTC count, and protocol.
python-obd discovers the vehicle's supported PID blocks at connection time. The server publishes only sensors found in those blocks, serializes access to the COM port, and reconnects once after a communication failure.
In simulation mode, the same six tools run through an in-process virtual connection. It advertises common sensors such as RPM, speed, coolant temperature, engine load, throttle position, intake data, MAF, fuel level, voltage, run time, and MIL distance. It also provides a simulated VIN, protocol, MIL status, and stored/pending DTCs. Clearing DTCs updates the simulator's state until the server restarts.
Requirements
Python 3.10 or newer.
An OBD-II-compatible vehicle, with ignition in the ON position (and engine running if required by the vehicle).
A classic Bluetooth ELM327 adapter that provides a Serial Port Profile (SPP).
On Windows, a Bluetooth outgoing COM port assigned to the adapter.
BLE-only adapters frequently do not provide a serial port and cannot be used directly with python-obd.
An adapter and vehicle are not required when using --simulation.
Install
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item config.example.json config.jsonEdit config.json and set port to the adapter's outgoing COM port:
{
"port": "COM3",
"baudrate": null,
"timeout": 30.0,
"fast": false,
"reconnect_attempts": 3,
"reconnect_delay": 2.0,
"transport": "stdio",
"host": "127.0.0.1",
"http_port": 8000,
"log_level": "INFO",
"simulation": false
}fast: false and a 30-second timeout are more tolerant of Bluetooth ELM327 clones. Configuration precedence is: command line > environment variables > JSON file > defaults.
Environment variable | Example |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Simulation mode
Start a Streamable HTTP server with generated data and no ELM327 connection:
.venv\Scripts\python.exe -m obd_mcp.server --simulation --transport streamable-httpOr start it over stdio:
.venv\Scripts\python.exe -m obd_mcp.server --simulationSimulation can also be enabled with "simulation": true in the JSON configuration or with OBD_SIMULATION=true. Command-line options have the highest precedence, so --no-simulation disables a value enabled by the environment or configuration file. Standard hardware mode remains the default.
Windows Bluetooth setup
Park safely, turn the ignition to ON, and plug the ELM327 into the vehicle's OBD-II port.
In Settings > Bluetooth & devices, pair the adapter (
OBDII,ELM327, etc.). Common PINs are1234and0000; prefer the manufacturer's PIN.In More Bluetooth settings > COM Ports or Device Manager, identify the adapter's outgoing COM port (for example,
COM8).Put that exact value in
config.json, for example:"port": "COM8".Close any diagnostic app that might have the COM port open.
Connect ChatGPT through Streamable HTTP
Use this option when the MCP configuration screen accepts a server URL.
Complete the Bluetooth setup above and save the correct COM port in
config.json.Start one terminal in the project directory and run:
.venv\Scripts\python.exe -m obd_mcp.server --config config.json --transport streamable-httpLeave that terminal open. It is the MCP server process; do not run
server.pyseparately.In ChatGPT, add the MCP server URL:
http://127.0.0.1:8000/mcpLeave the Bearer-token field empty and do not add custom headers. This local server does not implement authentication.
After connecting, start with
get_connection_status. Then calllist_supported_sensorsbeforeread_sensor.
The server attempts to connect to the ECU when it starts. If the vehicle or adapter is temporarily unavailable, the tools retry when called.
127.0.0.1 means only this computer can reach the server. Do not expose it to your LAN or the public internet without adding authentication and network controls, especially because clear_dtc is destructive.
Other ways to run it
Stdio
Use this when the MCP client launches local commands itself:
.venv\Scripts\python.exe -m obd_mcp.server --config config.jsonFor example, a desktop MCP client may use this Windows configuration:
{
"mcpServers": {
"obd2": {
"command": "C:\\path\\to\\OBD2-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "obd_mcp.server", "--config", "C:\\path\\to\\OBD2-mcp\\config.json"]
}
}
}MCP Inspector
.venv\Scripts\mcp.exe dev server.pyInteractive validator
The validator starts a temporary stdio server process itself, negotiates MCP, and provides a menu of safe checks. Do not start the HTTP server for this command.
.venv\Scripts\python.exe scripts\mcp_terminal_tester.py --config config.jsonTo exercise the complete MCP flow without a vehicle:
.venv\Scripts\python.exe scripts\mcp_terminal_tester.py --simulationOption 8 runs a non-destructive connectivity check: connection status, supported sensors, vehicle information, and DTCs. Option 7 requires typing CLEAR before it sends confirm: true.
To override the serial port for one test:
.venv\Scripts\python.exe scripts\mcp_terminal_tester.py --port COM8Troubleshooting
Symptom | Check |
No ECU connection | Ignition is ON, adapter has power, and the configured outgoing COM port is correct. |
Port cannot be opened | Close Torque, scan tools, terminal programs, or anything else using that COM port. |
No serial port after pairing | The adapter may be BLE-only rather than Bluetooth SPP. |
ChatGPT cannot connect | Confirm the server terminal is still running and the URL is exactly |
Sensor is unsupported | Call |
Development checks
python -m pip install -r requirements-dev.txt
pytest
mypy obd_mcp
ruff check .Available Tools
6 toolsclear_dtcA
Clear ECU DTCs and freeze-frame only after explicit user approval.
Set confirm=true; this may reset readiness monitors and temporarily turn off the MIL.
Inputs: confirm. Returns: object
get_connection_statusA
Check the ELM327/ECU connection, port, and OBD-II protocol.
Use this first when a vehicle may be off or disconnected.
Inputs: no named parameters. Returns: object
get_vehicle_infoA
Read VIN, Check Engine/MIL state, DTC count, and OBD-II protocol.
Inputs: no named parameters. Returns: object
list_supported_sensorsA
List live sensor PIDs discovered as supported by the vehicle.
Use these exact names with read_sensor.
Inputs: no named parameters. Returns: result
read_dtcA
Read stored and pending/current-cycle diagnostic trouble codes.
Includes python-OBD technical descriptions when known and does not modify the ECU.
Inputs: no named parameters. Returns: object
read_sensorB
Read one or several supported sensors and return values with units.
Examples: RPM, SPEED, COOLANT_TEMP, INTAKE_PRESSURE.
Inputs: sensors (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clear and distinct purpose: connection status, supported sensor list, live sensor reads, DTC reading, DTC clearing, and vehicle info. Potential overlap between get_connection_status and get_vehicle_info regarding protocol is minimal and contextually distinct.
All tool names follow a consistent snake_case verb_noun pattern (e.g., get_connection_status, read_sensor, clear_dtc). The verb choices are appropriate for each action and create a predictable API surface.
Six tools cover the core OBD-II operations without unnecessary bloat. The count is well suited to the domain and keeps the interface focused and manageable.
The set covers the essential OBD-II workflows: checking connectivity, discovering supported sensors, reading live data, retrieving DTCs, clearing DTCs, and obtaining vehicle identification. No critical operations appear missing for a read-focused OBD-II MCP server.
Related MCP Connectors
Reads your car through the AI ELM app and an OBD2 adapter: fault codes, live data, reports
Your car's drives, fuel use and engine health from its OBD-II port. Explains any fault code.
131Read your own vehicles' OBD-II scans, fault codes, telemetry and trips stored in OBD Vault.
AI Mechanic — understand car symptoms and OBD-II codes, check recalls, get repair guidance.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables LLMs to interact with vehicle CAN bus and OBD-II data through a simulated ECU environment. Provides tools for reading frames, decoding messages via DBC files, monitoring signals, and querying automotive diagnostics without requiring physical hardware.19 PyPI26MIT
- FlicenseAqualityDmaintenanceExposes a connected-vehicle OBD-II/telematics platform to AI agents, enabling vehicle health scoring, live data queries, DTC decoding, maintenance prediction, and gated remote commands via a pluggable data layer.9-
- AlicenseAqualityCmaintenanceA 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.71Apache 2.0
- AlicenseBqualityCmaintenanceA lightweight Bluetooth Low Energy debug MCP server for AI agents. It provides 21 tools for BLE scanning, connection, GATT read/write, descriptor access, MTU query, notification subscription, device recon, and engine diagnostics.21Apache 2.0