OpenOCD

OpenOCD MCP Server provides a lightweight MCP (Modular Control Protocol) service built on fastmcp to manage OpenOCD debugging sessions. It lets you switch projects, refresh targets, perform one-shot flashes, start and stop debug sessions, execute GDB commands, and query runtime status from a single, streamlined interface.

How to use

You can use this MCP server to control OpenOCD-based debugging workflows from an MCP client. Start the server with the runtime runner, configure debugging targets, and issue commands to flash, launch, or stop sessions. The server supports switching projects, refreshing targets, performing a one-time flash, starting and stopping debugging sessions, executing GDB commands, and querying status.

How to install

Prerequisites: you need Node.js installed to run the MCP server tooling. You also use the UV-based runner to execute the MCP service.

# Install Node.js if you do not have it
# Example for macOS with Homebrew
brew install node

# Install the MCP runtime tool if needed (example using npm)
npm install -g uv

# Or install locally in your project directory
npm install --save-dev uv

Run the MCP server

Use the following command to start the MCP server and connect to OpenOCD and GDB as needed. You can also start with a built-in SSE/HTTP transport for local clients.

uv run openocd-mcp --openocd-path openocd --gdb-path arm-none-eabi-gdb

Run in plain mode

If you want to start the server without extra path parameters, run the base command. The service will automatically read path configurations from the current directory’s config.json if present. Command-line arguments take precedence over environment variables, which take precedence over config.json values and built-in defaults.

uv run openocd-mcp

Enable SSE/HTTP mode for local clients

The default transport is stdio. To expose an SSE/HTTP endpoint for local clients (e.g., other tools or assistants), enable SSE mode.

uv run openocd-mcp -sse

Configure SSE details

You can customize the SSE endpoint by binding to a specific host and port and by setting the path under the SSE URL.

uv run openocd-mcp -sse --host 127.0.0.1 --port 9000 --path /sse

Environment variables

The server can also read environment configuration if you prefer to set values there.

Supported environment variables (shown for reference):

OPENOCD_PATH, GDB_PATH, OPENOCD_SCRIPTS

Available tools

set_project

Switch the current project directory context used for debugging targets.

refresh_debug_targets

Refresh the list of available debugging targets from the current project.

flash_download

Flash a firmware image to the target using the specified configuration.

debug_start

Start a debugging session for the selected configuration and firmware.

debug_stop

Stop an ongoing debugging session.

debug_command

Execute a GDB or debugging command in the active session.

debug_status

Query the current status of the debugging session and targets.

get_runtime_config

Retrieve the runtime configuration used by the MCP server.