The OpenROAD MCP server

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for jluarprecisioninno from gravatar.com jluarprecisioninno Avatar for openroad from gravatar.com openroad

Unverified details

These details have not been verified by PyPI
Meta
Report project as malware

Project description

OpenROAD MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with OpenROAD and ORFS (OpenROAD Flow Scripts).

Demo

OpenROAD MCP Demo

Watch full demo video

Features

  • Interactive OpenROAD sessions - Execute commands in persistent OpenROAD sessions with PTY support
  • Session management - Create, list, inspect, and terminate multiple sessions
  • Command history - Access full command history for any session
  • Performance metrics - Get comprehensive metrics across all sessions
  • Report visualization - List and read report images from ORFS runs

Requirements

  • OpenROAD installed and available in your PATH
  • OpenROAD-flow-scripts (ORFS) for complete RTL-to-GDS flows (optional but recommended)
  • Python 3.13+ or higher
  • uv package manager
    • Install: curl -LsSf https://astral.sh/uv/install.sh | sh

Support Matrix

MCP Client Supported Transport Mode(s) Config file
Claude Code ✅ STDIO .claude/settings.json
Claude Desktop ✅ STDIO ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor ✅ STDIO .cursor/mcp.json
GitHub Copilot (VS Code) ✅ STDIO .vscode/mcp.json
Gemini CLI ✅ STDIO ~/.gemini/settings.json
Windsurf ✅ STDIO ~/.codeium/windsurf/mcp_config.json
Cline ✅ STDIO VS Code globalStorage (see below)
Roo Code ✅ STDIO .roo/mcp.json
Continue ✅ STDIO ~/.continue/config.json
Zed ✅ STDIO ~/.config/zed/settings.json
JetBrains AI Assistant ✅ STDIO Settings UI
Amazon Q Developer CLI ✅ STDIO ~/.aws/amazonq/mcp.json
Augment Code ✅ STDIO VS Code settings.json
Warp ✅ STDIO Settings UI
Amp ✅ STDIO CLI-managed
Trae ✅ STDIO User config
Opencode ✅ STDIO opencode.json
Kiro ✅ STDIO Settings UI
Kilo Code ✅ STDIO .kilocode/mcp.json
Goose ✅ STDIO ~/.config/goose/config.yaml
Sourcegraph Cody ✅ STDIO VS Code settings.json
OpenAI Codex CLI ✅ STDIO ~/.codex/config.toml
PearAI ✅ STDIO ~/pearai/config.json
CodeBuddy ✅ STDIO ~/.codebuddy/config.jsonc
Hermes Agent ✅ STDIO ~/.hermes/config.yaml
GitHub Copilot CLI ✅ STDIO ~/.copilot/mcp-config.json
Oh My Pi ✅ STDIO .omp/mcp.json
OpenClaw ✅ STDIO ~/.openclaw/openclaw.json
AstrBot ✅ STDIO WebUI
DeepCode ✅ STDIO deepcode_config.json
nanobot ✅ STDIO nanobot.yaml
Crush ✅ STDIO .crush.json
Reasonix ✅ STDIO reasonix.toml
Other MCP clients ⚠️ STDIO Should work with standard STDIO transport

Getting Started

New to OpenROAD MCP? Check out our Quick Start guide.

For platform-specific setup instructions, see the Cross-Platform Guide.

Standard Configuration

The basic configuration for all MCP clients:

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ]
    }
  }
}

Note: The URL above is pinned to a specific release for supply chain safety. To always track the latest version instead, drop the @v0.5.5 suffix: "git+https://github.com/The-OpenROAD-Project/openroad-mcp".

For local development, use:

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/openroad-mcp",
        "run",
        "openroad-mcp"
      ]
    }
  }
}

Installation

Claude Code 
claude mcp add --transport stdio openroad-mcp -- uvx --from git+https://github.com/The-OpenROAD-Project/openroad-mcp openroad-mcp

Or add the standard configuration to .claude/settings.json.

Claude Desktop

Add the standard configuration to:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
Cursor

Add the standard configuration to .cursor/mcp.json.

GitHub Copilot (VS Code)

Add to .vscode/mcp.json (VS Code 1.99+). Note the different schema — servers key and "type": "stdio" required:

{
  "servers": {
    "openroad-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ]
    }
  }
}
Gemini CLI

Follow the Gemini MCP install guide, using the standard configuration above.

Windsurf

Add the standard configuration to ~/.codeium/windsurf/mcp_config.json.

Cline

Add to the Cline MCP settings file:

  • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
Roo Code

Add to .roo/mcp.json in your project root (or the equivalent user-level settings file via the Roo Code UI):

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
Continue

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
            "openroad-mcp"
          ]
        }
      }
    ]
  }
}
Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "openroad-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "--from",
          "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
          "openroad-mcp"
        ]
      },
      "settings": {}
    }
  }
}
JetBrains AI Assistant

Open Settings → Tools → AI Assistant → Model Context Protocol (MCP) and add a new server entry using the standard configuration.

Amazon Q Developer CLI

Add the standard configuration to ~/.aws/amazonq/mcp.json.

Augment Code

Add to your VS Code settings.json (User or Workspace scope):

{
  "augment.advanced": {
    "mcpServers": [
      {
        "name": "openroad-mcp",
        "command": "uvx",
        "args": [
          "--from",
          "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
          "openroad-mcp"
        ]
      }
    ]
  }
}
Warp

Open Settings → AI → MCP Servers → Add New MCP Server and enter:

  • Name: openroad-mcp
  • Command: uvx
  • Args: --from git+https://github.com/The-OpenROAD-Project/openroad-mcp openroad-mcp
Amp 
amp mcp add openroad-mcp uvx --from git+https://github.com/The-OpenROAD-Project/openroad-mcp openroad-mcp
Trae

Add the standard configuration to the MCP section of Trae's user settings (accessible via Settings → MCP).

Opencode

Add to opencode.json in your project root:

{
  "mcp": {
    "openroad-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ],
      "enabled": true
    }
  }
}
Kiro

Open the MCP configuration panel in Kiro and add a new server entry using the standard configuration.

Kilo Code

Add to .kilocode/mcp.json in your project root:

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ],
      "alwaysAllow": [],
      "disabled": false
    }
  }
}
Goose

Add to ~/.config/goose/config.yaml:

extensions:
  openroad-mcp:
    name: openroad-mcp
    type: stdio
    cmd: uvx
    args:
      - --from
      - git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5
      - openroad-mcp
    enabled: true
Sourcegraph Cody

Add to your VS Code settings.json:

{
  "openctx.providers": {
    "https://openctx.org/npm/@openctx/provider-mcp": {
      "transports": [
        {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
            "openroad-mcp"
          ]
        }
      ]
    }
  }
}
OpenAI Codex CLI

Add to ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[[mcp_servers]]
name = "openroad-mcp"
command = "uvx"
args = ["--from", "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5", "openroad-mcp"]
PearAI

PearAI uses the same config format as Continue. Add to ~/pearai/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "--from",
            "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
            "openroad-mcp"
          ]
        }
      }
    ]
  }
}
CodeBuddy

Add to ~/.codebuddy/config.jsonc (global) or .codebuddy/mcp.jsonc (project-scoped):

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ]
    }
  }
}
Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  - name: openroad-mcp
    transport: stdio
    command: uvx
    args:
      - --from
      - git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5
      - openroad-mcp
GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "openroad-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ]
    }
  }
}

Or run /mcp add inside a Copilot CLI session for guided setup.

Oh My Pi

Add to .omp/mcp.json (project-level) or ~/.omp/agent/mcp.json (global):

{
  "mcpServers": {
    "openroad-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ]
    }
  }
}
OpenClaw

Add to ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "openroad-mcp": {
        "command": "uvx",
        "args": [
          "--from",
          "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
          "openroad-mcp"
        ],
        "enabled": true
      }
    }
  }
}

Or run openclaw mcp add for guided setup.

AstrBot

Navigate to the AstrBot WebUI → MCP section → Add Server, and enter:

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5", "openroad-mcp"]
}

Requires uv installed on the host running AstrBot.

DeepCode

Add to deepcode_config.json in your project root:

{
  "tools": {
    "mcpServers": {
      "openroad-mcp": {
        "type": "stdio",
        "command": "uvx",
        "args": [
          "--from",
          "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
          "openroad-mcp"
        ]
      }
    }
  }
}
nanobot

Add to nanobot.yaml in your project root:

mcpServers:
  openroad-mcp:
    command: uvx
    args:
      - --from
      - git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5
      - openroad-mcp
Crush

Add to .crush.json (project-local) or ~/.config/crush/crush.json (global):

{
  "mcp": {
    "openroad-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5",
        "openroad-mcp"
      ]
    }
  }
}
Reasonix

Add to reasonix.toml (project root) or ~/.config/reasonix/config.toml (global):

[[plugins]]
name    = "openroad-mcp"
command = "uvx"
args    = ["--from", "git+https://github.com/The-OpenROAD-Project/openroad-mcp@v0.5.5", "openroad-mcp"]

Alternatively, use the standard .mcp.json format — Reasonix auto-discovers it.

Docker

🚧 Work in Progress: Docker deployment via GitHub Container Registry (GHCR) is coming soon.

MCP Registry

Once published to the MCP Registry, clients can discover and install directly:

uvx openroad-mcp

Verification

After configuration, restart your MCP client and verify the MCP server is running:

  1. The server should automatically start when your MCP client launches
  2. You can use OpenROAD tools through the MCP interface
  3. Check logs for any startup errors if tools are not available

Available Tools

Once configured, the following tools are available:

  • interactive_openroad - Execute commands in an interactive OpenROAD session
  • create_interactive_session - Create a new OpenROAD session
  • list_interactive_sessions - List all active sessions
  • terminate_interactive_session - Terminate a session
  • inspect_interactive_session - Get detailed session information
  • get_session_history - View command history
  • get_session_metrics - Get performance metrics
  • list_report_images - List ORFS report directory images
  • read_report_image - Read a ORFS report image

Troubleshooting

If the MCP server fails to start:

  1. Ensure uv is installed and available in your PATH
  2. Verify the path to openroad-mcp is correct
  3. Check that all dependencies are installed: make sync
  4. Review your MCP client logs for specific error messages

Development

Setup

# Install environment
uv venv
make sync

Testing

# Run core tests (recommended - excludes PTY tests that may fail in some environments)
make test

# Run interactive PTY tests separately (may have file descriptor issues in CI)
make test-interactive

# Run all tests including potentially problematic PTY tests
make test-all

# Format and check code
make format
make check

Note: Interactive PTY tests are separated because they may experience file descriptor issues in certain environments (containers, CI systems). The core functionality tests (make test) provide comprehensive coverage of the MCP integration without these environment-specific issues.

MCP Inspector

# Launch MCP inspector for debugging
# For STDIO transport: Set Command as "uv", Arguments as "run openroad-mcp"
make inspect

Contributing

We welcome contributions to OpenROAD MCP! Please see CONTRIBUTING.md for detailed instructions on how to get started, our development workflow, and code standards.

Support

If you encounter any issues or have questions, please open an issue on our GitHub issue tracker.

License

BSD 3-Clause License. See LICENSE file.

Built with ❤️ by Precision Innovations

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for jluarprecisioninno from gravatar.com jluarprecisioninno Avatar for openroad from gravatar.com openroad

Unverified details

These details have not been verified by PyPI
Meta

Release history Release notifications | RSS feed

This version

0.5.5

0.5.3

0.5.2

0.5.1

0.5.0

0.4.2

0.4.1

0.4.0

0.3.0

0.2.0

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openroad_mcp-0.5.5.tar.gz (18.4 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

openroad_mcp-0.5.5-py3-none-any.whl (46.7 kB view details)

Uploaded Python 3

File details

Details for the file openroad_mcp-0.5.5.tar.gz.

File metadata

  • Download URL: openroad_mcp-0.5.5.tar.gz
  • Upload date:
  • Size: 18.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for openroad_mcp-0.5.5.tar.gz
Algorithm Hash digest
SHA256 53ca89f56a91c44f6d775d3029d4fd002bdec9e8767668bbd75ea425ae8e6eed
MD5 1e53efa92a06534bf708cd65e32199c8
BLAKE2b-256 b371da101c3ce0659259c99b0186fc3bd635a0a103ceb6f3a9c7f773572d4576

See more details on using hashes here.

Provenance

The following attestation bundles were made for openroad_mcp-0.5.5.tar.gz:

Publisher: release.yml on The-OpenROAD-Project/OpenROAD-MCP

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openroad_mcp-0.5.5-py3-none-any.whl.

File metadata

  • Download URL: openroad_mcp-0.5.5-py3-none-any.whl
  • Upload date:
  • Size: 46.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for openroad_mcp-0.5.5-py3-none-any.whl
Algorithm Hash digest
SHA256 85bc737f7d206250a4c1ce035f6a171e2499a11f704f13f748e3b7d65957c27d
MD5 06a4ac159b1d121cfea67d3ab991a62c
BLAKE2b-256 defcb1f2ec2e41714286006cecc2a9ee0e567106d990caf1ffd61e74b089910b

See more details on using hashes here.

Provenance

The following attestation bundles were made for openroad_mcp-0.5.5-py3-none-any.whl:

Publisher: release.yml on The-OpenROAD-Project/OpenROAD-MCP

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page