visio-mcp

MCP (Model Context Protocol) server for drawing circuit schematics and diagrams in Microsoft Visio, driven by an LLM agent. MIT-licensed, 100% original code — no parts copied from other Visio MCP projects.

Why

Drawing schematic netlists in Visio programmatically usually fails because symbol pins live at unknown coordinates and wires end up floating next to the symbols. This server ships measured pin geometry for the classic Analog Circuit stencil: every master was rendered to a 240 DPI PNG and its pins were located pixel-exact. pin_point() turns those offsets into exact page coordinates, so wires land on the pins.

Related MCP server: ansys-aedt-mcp

Features

• Live COM engine — attaches to a running Visio (GetActiveObject) or launches a new instance (Dispatch); auto-answers modal dialogs; runs all COM on a single worker thread

• Stencil lock workaround — if a stencil is open in another Visio session (very common), a temporary copy is opened instead

• Tools: documents, pages, stencils, masters, shapes (drop / wire / label / junction / weight / delete / find / list), export (PNG/PDF/SVG/EMF…)

• Measured pin geometry for Analog Circuit.vss masters (NMOS1/PMOS1/Res1/Cap1/Ind2/balun/gnd/vdd) with orientation variants

• Bundled stencils — stencils/ ships Analog Circuit.vss, RFIC_lib.vss and RFsys_lib.vss so the examples run out of the box (third-party academic symbols, see stencils/README.md for provenance)

• Headless mock engine — the same tool layer runs without Visio, so the test suite works on Linux CI

• Example: complete two-stage differential 40 GHz LNA schematic generator

Requirements

Install

cd VISIO_MCP
python -m venv .venv
.venv\Scripts\pip install -e ".[dev]"

# stencils ship with the repo; point the server at them
export VISIO_MCP_STENCIL_DIRS="$PWD/stencils"

Probe Visio:

.venv\Scripts\python -m visio_mcp --check

Run as an MCP server (stdio)

.venv\Scripts\visio-mcp

Claude Code

{
  "mcpServers": {
    "visio": {
      "command": "C:/path/to/your/stencils/VISIO_MCP/.venv/Scripts/python.exe",
      "args": ["-m", "visio_mcp"],
      "env": {
        "VISIO_MCP_STENCIL_DIRS": "C:/path/to/your/stencils"
      }
    }
  }
}

Hermes Agent

mcp_servers:
  visio:
    command: "C:/path/to/your/stencils/VISIO_MCP/.venv/Scripts/python.exe"
    args: ["-m", "visio_mcp"]
    env:
      VISIO_MCP_STENCIL_DIRS: "C:/path/to/your/stencils"

Environment variables

Tools

Drawing recipe (agent workflow)

1. new_document(16, 9.5) — coordinates are inches

2. load_stencil("…/Analog Circuit.vss") — get a stencil key

3. drop_master(key, "NMOS1", x, y, flip_x=…) for every symbol

4. pin_point("NMOS1", x, y, "gate") — exact pin coordinate

5. draw_wire([[..], pin_point, ..]) — wires first, components on top (series elements cover the wire; use symbol_bounds to keep descents out of bodies)

6. add_junction at ≥3-wire nodes, add_label for names

7. export_page("png", "out.png") — inspect, iterate

Pitfalls

• Do not keep the output .vsdx open in Visio while regenerating it — SaveAs then fails with an "invalid DOS handle" error. Close the file first (or write to a new path).

• Temporary stencil copies must live next to the original stencil — files in %TEMP% are rejected by the Visio Trust Center file-block settings.

• If a user's interactive Visio session feels flaky (stencils open in compatibility mode, unsaved docs, ...), set VISIO_MCP_ATTACH=0 so the server drives its own dedicated instance.

Measured pin data

visio_mcp/data/pins_analog_circuit.json — offsets in inches relative to the drop point (y-up page coordinates), measured by PNG-render + pixel analysis. Variants encode rotations (angle) and mirrors (flip_x). Verified against the two-stage LNA example (all 21 connections pixel-checked).

Project layout

visio_mcp/
  engine.py        live COM engine (single worker thread, lazy win32com)
  mock_engine.py   headless engine for CI
  server.py        FastMCP app + tools
  pins.py          measured-geometry helpers
  data/pins_analog_circuit.json
stencils/           bundled Visio stencils (Analog Circuit / RFIC_lib / RFsys_lib)
examples/lna_two_stage.py   two-stage diff LNA schematic generator
tests/                      unit tests (headless)

License

MIT — the code, the measured pin-geometry JSON, and this documentation are original work of this project's author. The bundled stencils in stencils/ (Analog Circuit.vss, RFIC_lib.vss, RFsys_lib.vss) are third-party academic symbols (originally created at Fudan University) and are not covered by this project's MIT license — see stencils/README.md for their provenance and terms.