Openroad Mcp

Created By
luarss2 months ago
Overview

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 ClientSupportedTransport Mode(s)Notes
Claude CodeSTDIOFull support for all features
Gemini CLISTDIOFull support for all features
Other MCP clients⚠️STDIOShould 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/luarss/openroad-mcp",
        "openroad-mcp"
      ]
    }
  }
}

For local development, use:

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

Installation

Claude Code

Use the Claude Code CLI to add the OpenROAD MCP server:

claude mcp add --transport stdio openroad-mcp -- uvx --from git+https://github.com/luarss/openroad-mcp openroad-mcp
Gemini CLI

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

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

Server Config

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/luarss/openroad-mcp",
        "openroad-mcp"
      ]
    }
  }
}
Project Info
Created At
2 months ago
Updated At
2 months ago
Author Name
luarss
Star
-
Language
-
License
-
Category
Tags

Recommend Servers

View All
GovQL
@Alex Stout

# govql-mcp-server An MCP (Model Context Protocol) server for [GovQL](https://govql.us) — gives AI clients like Claude Desktop, Claude Code, and Cursor direct access to the US Congressional GraphQL API at [api.govql.us/graphql](https://api.govql.us/graphql) without bespoke HTTP wiring. For the design rationale (why FastMCP-Python, the passthrough+curated philosophy, roadmap through v0.4), see [design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md). ## What you can do with it Ask an agent questions like: - *"How did Vermont's two senators vote on the most recent nomination?"* - *"Which legislators in the 118th Congress switched parties during their service?"* - *"Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes in the most recent Congress."* The agent picks the right tool, writes the GraphQL query against the live schema, and parses the response — no manual API wrangling. ## Install The server runs as a per-client subprocess over stdio. Pick your client: ### Claude Desktop Edit `claude_desktop_config.json` (Settings → Developer → Edit Config): ```json { "mcpServers": { "govql": { "command": "uvx", "args": ["govql-mcp-server"] } } } ``` Restart Claude Desktop. The `govql` tools appear in the tools panel. ### Claude Code Add to `.mcp.json` in your project (or `~/.mcp.json` for global): ```json { "mcpServers": { "govql": { "command": "uvx", "args": ["govql-mcp-server"] } } } ``` ### Cursor Settings → MCP → Add Server. Use the same `command` / `args` as above. ### Other clients Any MCP-compatible client that supports stdio servers will work. The command is `uvx govql-mcp-server` with no required arguments. ## Tools | Tool | Purpose | |---|---| | `execute_graphql` | Run any GraphQL query against the GovQL endpoint. Returns the result plus an `last_ingest` timestamp so the agent can reason about data freshness. | | `list_types` | Returns the names and kinds of every type in the GovQL schema. Optional `kind` filter (`"OBJECT"`, `"INPUT_OBJECT"`, `"ENUM"`, etc.) to narrow further. Start here when you don't know what's queryable. | | `describe_type` | Returns one type's full details — fields, arg signatures, input fields, enum values. Call after `list_types` to learn the shape of a specific type before writing a query. | ## Configuration All env vars are optional — the package is zero-config for end users. | Env var | Default | Purpose | |---|---|---| | `GOVQL_ENDPOINT` | `https://api.govql.us/graphql` | Endpoint to query. Override to point at a local dev stack. | | `GOVQL_TIMEOUT_MS` | `30000` | Per-request HTTP timeout. | | `LOG_LEVEL` | `INFO` | Logging level. Logs go to stderr only (stdout is reserved for the MCP transport). | ## Limits (enforced by the upstream API) - Max query depth: 10 - Max query complexity: ~10 billion points (`first: N` multiplies child cost by N — keep page sizes reasonable on deeply nested queries) - Rate limit: 100 requests / 60 s per source IP A depth or complexity violation surfaces as a GraphQL `errors` entry in the tool response so the agent can adjust and retry. ## Data freshness Every `execute_graphql` response includes a `last_ingest` ISO timestamp. Vote data refreshes hourly; legislator data refreshes daily. ## Status Version 0.1.0 ships three foundational tools: a GraphQL passthrough (`execute_graphql`) and two narrow schema-discovery tools (`list_types`, `describe_type`). Curated higher-level tools (`find_legislator`, `get_voting_record`, `compare_voters`, etc.) are planned for subsequent releases — see [design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md) for the roadmap. ## Links - [GovQL project site](https://govql.us) - [GraphQL API](https://api.govql.us/graphql) - [Source / issues](https://github.com/govql/govql)

2 days ago