iccap-mcp-server

IC-CAP MCP Server

IC-CAP MCP Server connects ChatGPT desktop (Codex), Claude Code, ZCode, and other Model Context Protocol clients to Keysight IC-CAP. It provides 128 MCP tools and 15 embedded guides for project automation, measurement, simulation, optimization, and device-model extraction.

The gateway starts automatically with IC-CAP. An external broker isolates MCP dependencies from IC-CAP, reconnects after IC-CAP restarts, reports long-running job progress, captures supported Status-window feedback, and rejects unsafe paths before they reach the proprietary API.

Install in three steps

Requirements: Windows 11 x64, a Keysight IC-CAP installation using Python 3.8 through 3.12, and an MCP client. IC-CAP 2025 with Python 3.12 is the verified configuration; other accepted runtimes are compatibility candidates until they receive live IC-CAP testing.

1. Download iccap-mcp-server-<version>-windows-x64-setup.exe from GitHub Releases.
2. Run the installer, confirm the detected IC-CAP Python directory, and choose ChatGPT desktop (Codex), Claude Code CLI, and/or ZCode desktop.
3. Restart IC-CAP once, then restart the selected MCP client or open a new task.

The installer is fully offline after download. Users do not need to install Python, Git, or pip. If the IC-CAP Python directory is protected, only the small bootstrap command requests administrator approval; the main installer remains per-user.

A standard IC-CAP installation does not require ICCAP_PYTHONHOME; setup searches for its built-in tools\python runtime. If IC-CAP uses a custom Python, select that same directory in setup.

IC-CAP Status should show:

IC-CAP MCP gateway ready: session=... pid=... port=...

For supported versions, client-specific checks, repair, diagnostics, upgrade, uninstall, and source installation, see the Windows installation guide.

Test the connection

Start a new task in the configured MCP client and ask:

Perform a read-only IC-CAP MCP connection test. Call iccap_sessions_list,
iccap_health, iccap_status_get, and main_get_models. Do not simulate, save,
create, edit, delete, or run a macro. Report the session ID, IC-CAP PID,
gateway health, open models, and current Status warnings/errors.

If more than one IC-CAP process is open, select the intended session with iccap_session_select before reading model data. Gateway authentication tokens stay in the local session registry and are never returned by MCP tools.

What is included

• Automatic gateway startup with no recurring Macro click.
• Stdio transport for ChatGPT desktop (Codex), Claude Code, ZCode, and compatible clients.
• Optional Streamable HTTP on loopback for URL-based clients.
• Automatic discovery and reconnection after IC-CAP restarts.
• Explicit session selection for multiple IC-CAP processes.
• Asynchronous simulation, measurement, transform, Macro, and plot jobs.
• Incremental Status output and supported optimizer progress.
• Best-effort modal error-dialog capture and structured failures.
• Stable validation, non-overwriting defaults, recovery checkpoints, and a redacted operation journal.

The process and failure boundaries are documented in Architecture and failure semantics.

Long-running work

setup_simulate, setup_measure, transform_execute, macro_execute, and plot_display accept run_async=true and return a job_id.

• iccap_job_get returns state, result, errors, and parsed progress.
• iccap_job_list lists recent jobs.
• iccap_job_logs returns incremental Status output.
• iccap_job_cancel requests IC-CAP Stop Activity when available.
• iccap_status_get reads the current Status snapshot, including supported optimizer progress started manually in IC-CAP.

Cancellation is confirmed only when Stop Activity is found and invoked. A blocked native IC-CAP call cannot be killed safely by Python.

Safety boundary

• Existing targets are preserved unless overwrite=true is explicit.
• Overwrite and delete operations first create a managed Save As No Data checkpoint under %LOCALAPPDATA%\iccap-mcp\checkpoints.
• A failed checkpoint blocks mutation unless allow_without_checkpoint=true is explicitly accepted.
• IC-CAP locators must be absolute and are validated before dispatch.
• Calls are serialized on the IC-CAP UI thread.
• The redacted journal is stored at %LOCALAPPDATA%\iccap-mcp\operations.jsonl.

These safeguards cannot make proprietary C extensions transactional. A vendor crash, arbitrary Macro, instrument operation, malformed transform, or native deadlock can still block IC-CAP or lose work since the last save. Work on project copies and save verified milestones.

Configuration

Variable	Default	Purpose
ICCAP_PYTHONHOME	unset	Optional custom Python directory used by IC-CAP
ICCAP_MCP_GATEWAY_PORT	0	Gateway port; 0 selects a free loopback port
ICCAP_MCP_TOOL_TIMEOUT	60	Interactive broker wait timeout in seconds
ICCAP_MCP_JOB_TIMEOUT	86400	Long-job gateway deadline in seconds
ICCAP_MCP_WORKSPACE	./iccap_mcp_workspace	Allowed plot/export workspace
ICCAP_MCP_ALLOW_EXTERNAL_FILES	unset	Set 1 to allow MDM files outside the workspace

Do not expose the broker or in-process gateway to an untrusted network.

Development

The packaged installer is recommended for normal use. Contributors can use a separate Python 3.12 environment:

git clone https://github.com/Solitario119/iccap-mcp-server.git
cd iccap-mcp-server
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q

Build the offline runtime and installer with:

.\.venv\Scripts\python.exe -m pip install -e ".[installer-build]"
.\scripts\build_runtime.ps1 -Python .\.venv\Scripts\python.exe
.\scripts\build_installer.ps1 -SkipRuntime

Inno Setup 6 is required only to compile the installer. Live verification scripts under scripts/verify_live_*.py require a licensed IC-CAP process; mutation checks require an explicitly confirmed disposable model.

License and trademarks

Released under the MIT License. This independent open-source project is not affiliated with, endorsed by, or sponsored by Keysight Technologies. IC-CAP and Keysight are trademarks of their respective owner.