visio-mcp

An MCP server that drives the Microsoft Visio window you already have open.

It attaches to the running Visio instance through the COM running-object table, so the drawing on your screen is the drawing the model sees. It never launches a second, hidden copy of Visio and it never opens files behind your back — whatever is in front of you is what gets read and edited, live, with each tool call landing as a single Ctrl+Z step.

you: "the approval box should say 'Legal review' and hang off the risk step"
     -> visio_list_shapes, visio_render_page, visio_set_shape_text, visio_connect_shapes

Requirements

• Windows, with Microsoft Visio installed (desktop Visio — the web app has no COM API)
• Python 3.10 or newer
• pywin32, installed automatically on Windows

The server itself must run on the same Windows machine as Visio. It can’t reach a Visio running on another host, in a VM, or in Visio for the web.

Install

git clone https://github.com/isiec9ai/MCP.git visio-mcp
cd visio-mcp
py -m venv .venv
.venv\Scripts\pip install -e .

Point a client at it

Open Visio with the drawing you care about, then add the server.

Claude Code

claude mcp add visio -- C:\path\to\visio-mcp\.venv\Scripts\visio-mcp.exe

Claude Desktop — in %APPDATA%\Claude\claude_desktop_config.json (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "visio": {
      "command": "C:\\path\\to\\visio-mcp\\.venv\\Scripts\\visio-mcp.exe",
      "args": []
    }
  }
}

Ask for visio_status first; it tells you which instance is attached and what it has open.

Tools

Everything defaults to the document and page you are looking at. Pass document (file name or 1-based index) and page (name or 1-based index) to work elsewhere. Coordinates and sizes are inches from the bottom-left of the page, and a shape’s x/y is its centre — matching Visio’s own ShapeSheet.

Reading

Editing

Staying in control

• Nothing is written to disk unless visio_save is called. Close without saving and every edit is gone.

• Each tool call is one undo step. Writes run inside a Visio undo scope, so a single Ctrl+Z reverses a whole visio_add_shape, not half of it.

• --read-only publishes only the inspection tools. The write tools are not registered at all, so a client cannot call them even by name:

  visio-mcp --read-only          # or set VISIO_MCP_READ_ONLY=1
  

• visio_undo pops whatever is on top of Visio’s undo stack, which may be your last edit rather than the model’s. Prefer Ctrl+Z yourself when it matters.

Trying it without Visio

--fake swaps in an in-memory sample drawing — a three-box flowchart — so you can wire the server into a client and explore every tool on any OS:

visio-mcp --fake

Troubleshooting

“No running Visio instance was found”

• Visio has to be running, with at least one drawing open.
• Privilege levels have to match. A server started from an elevated terminal cannot see a normally-launched Visio, and vice versa — the running-object table is per integrity level. Start both the same way.
• Visio for the web and Visio Viewer expose no automation API.

It attached to the wrong instance. With several Visio processes running, the running-object table hands out whichever registered first. Close the ones you don’t want, or use visio_list_documents to confirm before editing.

A tool reports the connection was lost. Visio was closed or restarted. The server re-attaches on the next call; run visio_status to confirm.

visio_add_shape can’t find a master. Run visio_list_masters to see what the drawing and its open stencils actually offer, or pass stencil with a name Visio knows (BASIC_U.VSSX) or a full path to a .vssx.

Development

pip install -e ".[dev]"
pytest

The suite runs anywhere: src/visio_mcp/fake_backend.py implements the same contract as the COM backend (src/visio_mcp/backend.py defines it), so the whole tool surface is exercised without Windows. The COM layer itself needs a real Visio to test against.

Layout:

Licence

MIT