Xcelium MCP Server

MCP (Model Context Protocol) server that enables AI assistants to control Cadence Xcelium/SimVision in real time via a Tcl socket bridge. Supports automated RTL/gate-level debugging with watchpoints, binary search, checkpoints, and SHM probe control.

Architecture

┌──────────────┐  stdio   ┌───────────────────┐  TCP    ┌─────────────────────┐
│ AI Assistant  │ <------> │ Python FastMCP     │ <-----> │ mcp_bridge.tcl      │
│ (Claude, etc) │          │ Server (25 tools)  │ :9876  │ inside xmsim/SV     │
└──────────────┘          └────────────────────┘        │ (13 meta commands)  │
                                                         └─────────────────────┘

Installation

pip install -e .

# With screenshot support (requires ghostscript)
pip install -e ".[screenshot]"

# With dev dependencies
pip install -e ".[dev]"

Setup

1. Simulator Side (Linux server)

Load the Tcl bridge when launching xmsim or SimVision:

# Batch mode (no GUI license needed)
xmsim -64bit -input mcp_bridge.tcl top

# SimVision GUI mode
simvision -64bit -input mcp_bridge.tcl dump.shm

The bridge listens on TCP port 9876 by default. Override with:

export MCP_BRIDGE_PORT=9877

Bridge signals readiness by creating /tmp/mcp_bridge_ready_9876.

2. AI Tool Configuration

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "xcelium-mcp": {
      "type": "stdio",
      "command": "ssh",
      "args": ["-o", "BatchMode=yes", "sim-server", "/path/to/xcelium-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "xcelium": {
      "command": "xcelium-mcp"
    }
  }
}

3. SSH Tunnel (remote server)

# Forward port 9876 in ~/.ssh/config
Host sim-server
    LocalForward 9876 localhost:9876

Available Tools (25)

Connection & Control (1-7)

Signal Inspection (8-13)

Waveform (14-16)

Debug & Screenshot (17-18)

Advanced Debug (19-25)

Debugging Workflows

Quick Bug Hunt (watchpoint)

connect_simulator()
watch_signal(signal="top.dut.r_state", op="==", value="4'hF")
sim_run(duration="100us")          # stops at exact clock edge
get_signal_value(signals=["top.dut.r_state", "top.dut.r_data"])
watch_clear()
shutdown_simulator()               # always use this, never disconnect

Automated Time Search (bisect)

connect_simulator()
bisect_signal(
    signal="top.dut.r_error", op="==", value="1'b1",
    start_ns=0, end_ns=1000000,    # 0-1ms range
    precision_ns=100                # 100ns precision
)
# Returns iteration log + final narrowed time range
shutdown_simulator()

Long Simulation with SHM Control

connect_simulator()
probe_control(mode="disable")       # no SHM recording
sim_run(duration="50ms")            # skip uninteresting region
probe_control(mode="enable")        # start recording
sim_run(duration="10ms")            # capture region of interest
shutdown_simulator()

Checkpoint & Replay

connect_simulator()
sim_run(duration="10ms")
save_checkpoint(name="before_bug")
sim_run(duration="5ms")             # analyze bug region
restore_checkpoint(name="before_bug")  # go back
sim_run(duration="5ms")             # try different analysis
shutdown_simulator()

Key Rules

1. Always specify duration in sim_run to prevent hang on infinite loops
2. Always use shutdown_simulator to end sessions (preserves SHM data)
3. Never use disconnect_simulator to end sessions (SHM not flushed)
4. Gate-level sim: increase timeout with sim_run(timeout=1800) if needed
5. Bridge ready: check /tmp/mcp_bridge_ready_<port> file instead of TCP ping

Tcl Bridge Meta Commands

The bridge (mcp_bridge.tcl) accepts these meta commands over TCP:

Any other input is evaluated as a raw Tcl/SimVision command.

Testing

pytest tests/

Requirements

• Python >= 3.10
• mcp >= 1.0.0
• xmsim or SimVision (Cadence Xcelium) with Tcl console
• ghostscript (optional, for EPS to PNG screenshot conversion)

License

MIT