**LTspice MCP for macOS**

💡 User Note & SOP Context: This document serves as a personal Standard Operating Procedure (SOP) to streamline my own mental workflow and automation setup. No source code in this repository has been altered. Full credit for the engineering, logic, and core architecture belongs entirely to the original developers and the upstream projects credited below.

**Model Context Protocol (MCP) server** that enables agents and MCP clients to control LTspice on macOS for simulation, schematic generation, data extraction, verification, and rendering.

This project supports practical automation with reliable execution, reproducible artifacts, and outputs that closely match native LTspice behavior.

**Credited to:**
- [gtnoble/ngspice-mcp](https://github.com/gtnoble/ngspice-mcp)
- [luc-me/ltspiceMCP](https://github.com/luc-me/ltspiceMCP)
- [xuio/ltspice-mcp](https://github.com/xuio/ltspice-mcp) (core architecture and ScreenCaptureKit integration)

---

## What You Can Do

- Run LTspice simulations via MCP (`simulateNetlistFile`, `runSimulation`, queue tools).
- Generate and refine schematics (`createSchematic*`, lint/clean/debug tools).
- Render authentic LTspice images for schematics, plots, and symbols.
- Query RAW vectors and derive analysis metrics (bandwidth, margins, rise/fall times, settling time).
- Automate `.meas` statements and assertion-driven verification workflows.
- Execute stepped and Monte Carlo studies with structured result outputs.

---

## Quick Start

### 1. Prerequisites
- macOS with LTspice installed (default path: `/Applications/LTspice.app`).
- Python 3.11 or higher.
- `uv` (recommended) or `pip`.

### 2. Installation
```bash
uv sync
```

For pip:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 3. Start the MCP Daemon
```bash
./scripts/ltspice_mcp_daemon.sh start
./scripts/ltspice_mcp_daemon.sh status
```

Default endpoint: `http://127.0.0.1:8765/mcp`

### 4. Grant macOS Permissions (One-Time)
```bash
./scripts/ltspice_mcp_daemon.sh trigger-initial-permissions
./scripts/ltspice_mcp_daemon.sh check-accessibility
```

---

## Claude Desktop Integration

The architecture uses Anthropic’s Model Context Protocol (MCP). Claude can actively call remote tools on your local machine via Server-Sent Events (SSE).

### Configuration File
Edit the global configuration:
```bash
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

Merge or replace the `mcpServers` section:
```json
{
  "mcpServers": {
    "ltspice-mcp": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp"]
    }
  }
}
```

### Operating Instructions

**Step 1: Start the Local Daemon**  
Before using Claude:
```bash
./scripts/ltspice_mcp_daemon.sh stop
./scripts/ltspice_mcp_daemon.sh start
```

Verify the process is listening on `http://127.0.0.1:8765/mcp`.

**Step 2: Prompting Claude**  
Restart Claude Desktop (Cmd + Q). Confirm the plug/hammer icon appears. Use intent-driven prompts such as:

- *AC Analysis:*  
  “Please use the local ltspice-mcp tool. Locate rc_lowpass_ac.asc in my common circuits directory. Run the AC sweep and extract a uniform decade-spaced subsample of the complex out-node vector data.”

- *Transient Analysis:*  
  “Using component definitions from the prior AC analysis (tau ≈ 0.1 ms), generate a transient netlist for a step response from 0 to 1 ms. Run headlessly and return the interpolated output voltages.”

**Step 3: Shut Down**  
```bash
./scripts/ltspice_mcp_daemon.sh stop
```

---

## Client Configuration

### URL-Based MCP Clients
```toml
[mcp_servers.ltspice]
url = "http://127.0.0.1:8765/mcp"
enabled = true
```

### Claude Desktop (mcp-remote)
See the JSON configuration above.

### Stdio (Subprocess) Mode
```json
{
  "mcpServers": {
    "ltspice-mcp": {
      "command": "ltspice-mcp",
      "args": ["--transport", "stdio"],
      "cwd": "/absolute/path/to/ltspice-mcp"
    }
  }
}
```

---

## Core Capabilities

### Setup and Diagnostics
- `getLtspiceStatus`, `getLtspiceUiStatus`
- `daemonDoctor`, `tailDaemonLog`, `getRecentErrors`, `getCaptureHealth`

### Simulation and Queueing
- `simulateNetlist`, `simulateNetlistFile`, `runSimulation`
- `queueSimulationJob`, `listJobs`, `jobStatus`, `cancelJob`, `listJobHistory`

### Schematic Workflows
- `createSchematic`, `createSchematicFromNetlist`, `createSchematicFromTemplate`
- `validateSchematic`, `lintSchematic`, `autoDebugSchematic`
- `inspectSchematicVisualQuality`, `autoCleanSchematicLayout`

### Data, Measurements, and Verification
- `getPlotNames`, `getVectorsInfo`, `getVectorData`, `getLocalExtrema`
- `getBandwidth`, `getGainPhaseMargin`, `getRiseFallTime`, `getSettlingTime`
- `parseMeasResults`, `runMeasAutomation`, `runVerificationPlan`, `runSweepStudy`

### Native LTspice Rendering
- `renderLtspiceSchematicImage`
- `renderLtspicePlotImage`, `renderLtspicePlotPresetImage`
- `renderLtspiceSymbolImage`
- `startLtspiceRenderSession`, `endLtspiceRenderSession`

---


## Daemon Operations
```bash
./scripts/ltspice_mcp_daemon.sh start
./scripts/ltspice_mcp_daemon.sh restart
./scripts/ltspice_mcp_daemon.sh stop
./scripts/ltspice_mcp_daemon.sh status
./scripts/ltspice_mcp_daemon.sh logs --lines 200
./scripts/ltspice_mcp_daemon.sh logs --follow
```

Permission helpers:
```bash
./scripts/ltspice_mcp_daemon.sh trigger-screen-recording-permission
./scripts/ltspice_mcp_daemon.sh trigger-accessibility-permission
```

---

## Acknowledgments & Architecture Credits

This automation matrix adapts underlying client-server abstraction layers and local operating system hooks from public framework builds.
* **Core Application Engine:** Heavily extends and builds upon the native macOS tooling layout pioneered by **[xuio/ltspice-mcp](https://github.com/xuio/ltspice-mcp)**. Special recognition to the original architecture for enabling ScreenCaptureKit hooks and automated multi-window script handlers.
* **Protocol Core:** Driven by the Anthropic [Model Context Protocol (MCP)](https://modelcontextprotocol.io) leveraging `mcp-remote` serialization bridges.