Skip to main content
Glama
joelcanepa

OBD-II MCP Server

by joelcanepa
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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.

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 with confirm: 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.

Related MCP server: MCP-CAN

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.

Install

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item config.example.json config.json

Edit 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"
}

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

OBD_PORT

COM3 or /dev/rfcomm0

OBD_BAUDRATE

38400

OBD_TIMEOUT

30

OBD_FAST

false

OBD_RECONNECT_ATTEMPTS

3

OBD_RECONNECT_DELAY

2

OBD_MCP_TRANSPORT

stdio or streamable-http

OBD_MCP_HOST, OBD_MCP_HTTP_PORT

127.0.0.1, 8000

Windows Bluetooth setup

  1. Park safely, turn the ignition to ON, and plug the ELM327 into the vehicle's OBD-II port.

  2. In Settings > Bluetooth & devices, pair the adapter (OBDII, ELM327, etc.). Common PINs are 1234 and 0000; prefer the manufacturer's PIN.

  3. In More Bluetooth settings > COM Ports or Device Manager, identify the adapter's outgoing COM port (for example, COM8).

  4. Put that exact value in config.json, for example: "port": "COM8".

  5. 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.

  1. Complete the Bluetooth setup above and save the correct COM port in config.json.

  2. Start one terminal in the project directory and run:

    .venv\Scripts\python.exe -m obd_mcp.server --config config.json --transport streamable-http

  3. Leave that terminal open. It is the MCP server process; do not run server.py separately.

  4. In ChatGPT, add the MCP server URL:

    http://127.0.0.1:8000/mcp

  5. Leave the Bearer-token field empty and do not add custom headers. This local server does not implement authentication.

  6. After connecting, start with get_connection_status. Then call list_supported_sensors before read_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.json

For 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.py

Interactive 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.json

Option 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 COM8

Troubleshooting

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 http://127.0.0.1:8000/mcp.

Sensor is unsupported

Call list_supported_sensors and use an exact returned sensor name.

Development checks

python -m pip install -r requirements-dev.txt
pytest
mypy obd_mcp
ruff check .

Available Tools

6 tools
clear_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
confirmNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that clearing may 'reset readiness monitors' and 'temporarily turn off the MIL', and it clearly mentions the freeze-frame data is cleared. These side effects are critical for an agent to know before invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the main action and the critical approval requirement, followed by the parameter instruction and side effects. No fluff; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter), the description covers the action, the approval requirement, parameter usage, and side effects. The output schema exists, so return-value details are not required. The tool is fully understood with what's provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explicitly explains the 'confirm' parameter by instructing 'Set confirm=true', which conveys that this boolean is a safety confirmation gate. This adds meaning beyond the schema's default value and is sufficient for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Clear ECU DTCs and freeze-frame') and distinguishes itself from the read-only sibling 'read_dtc' by using the verb 'clear' rather than 'read'. The resource and operation are unambiguous, leaving no room for confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly requires 'explicit user approval' and instructs the agent to 'Set confirm=true', providing a direct precondition for invoking the tool. This is clear guidance on when (and only when) the tool should be used, and it implicitly contrasts with the read-only siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_connection_statusA

Check the ELM327/ECU connection, port, and OBD-II protocol.

Use this first when a vehicle may be off or disconnected.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It describes what is checked but does not state whether the operation is read-only, what it returns, or what happens if the connection fails. For a status-check tool, this is a notable omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the action and purpose. The second sentence gives targeted usage guidance. No fluff or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no params) and has an output schema (not shown) that likely explains return values. The description provides the purpose and a clear usage context. It could be slightly more explicit about the nature of the 'status' but remains complete for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and the schema has no properties. Per the rubric, the baseline is 4. The description adds no parameter-related information because none exists, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check') and names the exact resources (ELM327/ECU connection, port, OBD-II protocol). This clearly distinguishes it from sibling tools like read_sensor or read_dtc, which are data-gathering operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states a usage condition: 'Use this first when a vehicle may be off or disconnected.' This gives clear context on when to invoke it, though it doesn't mention exclusions or compare to alternatives directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_vehicle_infoA

Read VIN, Check Engine/MIL state, DTC count, and OBD-II protocol.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description itself must carry behavioral disclosure. The verb 'Read' signals a non-destructive operation, and the field list clarifies it returns a snapshot (e.g., DTC count rather than DTC details). It does not discuss prerequisites like an active OBD connection or error behavior, but for a read-only info tool the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is one short sentence that front-loads the action and enumerates the return contents. Every word contributes; there is no fluff or repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-argument info tool with an output schema, the description covers the main data categories an agent needs to anticipate. It does not add usage context or sibling differentiation, but those are largely covered by the field list and output schema; the remaining gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about arguments. Per the baseline for parameterless tools, this is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Read') and names a precise resource plus the exact fields returned: VIN, Check Engine/MIL state, DTC count, and OBD-II protocol. This distinguishes it from siblings like read_dtc (actual codes) and get_connection_status (connection state), even without explicit comparisons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a use case—fetching a vehicle overview/emissions status—but does not state when to choose it over read_dtc or list_supported_sensors, nor when not to use it. There are no explicit alternatives or exclusions, so the agent must infer routing from the field list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_supported_sensorsA

List live sensor PIDs discovered as supported by the vehicle.

Use these exact names with read_sensor.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry behavioral disclosure. It states the tool lists supported sensor PIDs and that the output names are exact for read_sensor. However, it does not mention edge cases (e.g., empty list when no sensors are supported), prerequisites (like requiring an active connection), or any performance characteristics. This is a minimal disclosure for a simple tool, but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences. The first states the purpose, and the second gives a direct usage hint. There is no fluff or redundancy; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (no parameters, simple list operation) and the existence of an output schema (which likely describes the return format), the description covers the essential purpose and usage hint. It doesn't mention prerequisites like connection status, but for a simple list tool this is a minor gap. Overall, it is sufficiently complete for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is nothing to document beyond the empty schema. The description adds no parameter information because none exist. The mention of 'exact names' pertains to the output, not parameters. Baseline of 4 applies for tools with no parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action and resource: 'List live sensor PIDs discovered as supported by the vehicle.' It clearly distinguishes from siblings like read_sensor (which reads a single sensor) and get_vehicle_info (which returns general info). The second sentence reinforces purpose by indicating the names are meant for read_sensor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: before read_sensor, to obtain the exact sensor names. It explicitly instructs to use these names with read_sensor, providing a usage pattern. It does not explicitly list exclusions or alternatives, but the context is clear enough given the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_dtcA

Read stored and pending/current-cycle diagnostic trouble codes.

Includes python-OBD technical descriptions when known and does not modify the ECU.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool does not modify the ECU, which is a key behavioral trait for a read operation. It also mentions that technical descriptions are included when known, adding some context beyond the name. However, it does not mention connection requirements, error behavior, or any other side effects, and since annotations are absent, the description carries the full burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the primary purpose. Every word adds value, and there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with an output schema, the description covers the essential information: what it reads, that it includes descriptions, and that it's non-destructive. The only gap is usage guidance, which is captured separately. Overall, it's adequate for the agent to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description has nothing to add about parameter semantics. The schema coverage is trivially 100%, and the baseline for zero-parameter tools is 4, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (read) and resource (diagnostic trouble codes), and specifies the scope (stored and pending/current-cycle). It does not explicitly name sibling tools, but the purpose is unambiguous and distinct from clearing codes or reading sensors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. The description does not mention that clear_dtc is for erasing codes or that read_sensor is for live data, so the agent must infer the appropriate context from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_sensorB

Read one or several supported sensors and return values with units.

Examples: RPM, SPEED, COOLANT_TEMP, INTAKE_PRESSURE.

ParametersJSON Schema
NameRequiredDescriptionDefault
sensorsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must disclose behavioral traits fully. It only mentions that values are returned with units, which is minimal. It does not explicitly state that the operation is read-only, nor does it describe error handling, permissions, side effects, or the structure of the response. For a tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The first sentence states the purpose and the second gives examples. It is front-loaded and efficient, with every word earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool, the description is still incomplete. It lacks guidance on how to discover supported sensors, what happens with invalid sensor names, and how units are formatted. The output schema may cover return structure, but the input parameter semantics and error behavior are not clarified. An agent would need to make assumptions to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides examples of sensor names but does not explicitly explain that the 'sensors' parameter accepts a sensor name or an array of names, nor does it clarify format, case sensitivity, or constraints. The examples imply the usage but do not fully cover the parameter's semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads one or several sensors and returns values with units, with concrete examples (RPM, SPEED, COOLANT_TEMP, INTAKE_PRESSURE). It is a specific verb+resource and is easily distinguished from siblings like read_dtc (diagnostic codes) and list_supported_sensors (listing sensors). No ambiguity remains about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention that list_supported_sensors should be consulted first to see available sensors, nor does it state any exclusions or specific contexts. The usage context is only implied, not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.1.0
    • First observedclear_dtc
    • First observedget_connection_status
    • First observedget_vehicle_info
    • First observedlist_supported_sensors
    • First observedread_dtc
    • First observedread_sensor
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP-CAN

    farzadnadiri
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables 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.
    13
    MIT

  • connected-vehicle-health

    imsnawaz
    F
    license
    A
    quality
    C
    maintenance
    Exposes 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
    -

  • OBD MCP Server

    ayhammouda
    A
    license
    A
    quality
    B
    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
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/joelcanepa/OBD2-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server