openroad-mcp

openroad-mcp

An MCP server that provides tools for interacting with OpenROAD and OpenROAD-flow-scripts (ORFS).

Requirements

• Node.js 22+
• OpenROAD installed and on your PATH (installation guide)
• OpenROAD-flow-scripts for report image tools (optional)

Quick start

Add this to your MCP client configuration:

{
  "mcpServers": {
    "openroad-mcp": {
      "command": "npx",
      "args": ["-y", "openroad-mcp"]
    }
  }
}

See the full installation guide for per-client configuration for Cursor, Claude Code, GitHub Copilot, and 25+ other clients.

Tools

tool	description
interactive_openroad_query	Execute a read-only OpenROAD command (whitelist-enforced)
interactive_openroad_exec	Execute a state-modifying OpenROAD command
create_interactive_session	Create a named session with custom command and environment
list_interactive_sessions	List all active and terminated sessions
terminate_interactive_session	Terminate a session (SIGTERM or SIGKILL)
inspect_interactive_session	Detailed metrics for one session
get_session_history	Command history with optional limit and search
get_session_metrics	Aggregate metrics across all sessions
list_report_images	List .webp report images from an ORFS run
read_report_image	Read a report image and return it as a viewable image block
grep_session_output	Search output of commands already run in a session
read_orfs_metrics	Read a design's per-stage metrics, rules-base gates and log diagnostics
run_orfs_stage	Run an ORFS flow stage via make as a tracked background job
get_orfs_job	Poll a flow run: progress, log tail, and metrics once it finishes
cancel_orfs_job	Terminate a flow run and every process it spawned

Full parameter reference and wire-format shapes: docs/API.md

Security model

The server enforces a three-tier Tcl command whitelist on commands sent to OpenROAD:

• BLOCKED_COMMANDS — rejected in both tools (OS-level escape vectors)
• EXEC_ONLY_PATTERNS — rejected in interactive_openroad_query, allowed in interactive_openroad_exec
• READONLY_PATTERNS — allowed in both tools

Details: docs/SECURITY.md

Docker

docker run --rm -i ghcr.io/the-openroad-project/openroad-mcp:latest

Configuration

The server reads configuration from environment variables. Key variables:

variable	default	description
OPENROAD_MAX_SESSIONS	50	Maximum concurrent sessions
OPENROAD_COMMAND_TIMEOUT	30.0	Default per-command timeout in seconds
ORFS_FLOW_PATH	~/OpenROAD-flow-scripts/flow (auto-detected if unset)	Path to ORFS flow directory
OPENROAD_WHITELIST_ENABLED	true	Enable Tcl command whitelist
OPENROAD_IMAGE_MAX_BASE64_KB	1024	Report-image payload budget in KB of base64
OPENROAD_MAX_FLOW_JOBS	2	Concurrent run_orfs_stage runs

Full list: docs/SECURITY.md#environment-variable-reference

Contributing

See CONTRIBUTING.md.

License

BSD 3-Clause. See LICENSE.