visio-mcp

An MCP server that drives Microsoft Visio desktop via COM automation to draw diagrams for you: flowcharts, block diagrams, and Azure/AWS architecture diagrams using the official stencils. Claude (or any MCP client) drops real Visio masters, glues dynamic connectors, runs Visio's auto-layout, and exports a PNG of the page so the AI can see the result and iterate.

Runs on Windows only (it automates the Visio desktop app through COM). The codebase is developed and unit-tested cross-platform, but the server must run on a Windows machine with Visio installed.

Requirements

• Windows 10/11

• Microsoft Visio desktop (any recent version; must be installed and activated)

• Python 3.10+ and uv

• Claude Code (or Claude Desktop) on the same machine

Related MCP server: Draw.io MCP Server

Setup (on the Windows machine)

git clone <this repo> C:\tools\visio_mcp   # or copy the folder
cd C:\tools\visio_mcp
uv sync

Azure / AWS icons

Visio ships them built-in — no downloads needed. Visio 16 / Microsoft 365 installs include ~130 stencils (Azure, AWS, networking, and more) under <Office install>\root\Office16\Visio Content\<locale>\ — e.g. AZURESTORAGE_U.VSSX, AWSSTORAGE_U.VSSX. They resolve by bare filename, so open_stencil("AZURESTORAGE_U.VSSX") (or a fuzzy match like open_stencil("azurestorage")) works out of the box. visio_status lists them in builtin_cloud_stencils, and there are also dedicated **Azure Diagrams** / **AWS Diagrams** templates (Azure, AWS) that create_document can start from.

Some masters go by different names than you might guess — the server auto-resolves common ones (Private Endpoint → Private Link, Amazon S3 → Bucket with Objects, IAM → Security Identity and Compliance) and tells you when a concept is a container rather than a master (subnets, VNets, VPCs → add_container).

For older Visio versions or extra vendor packs, download stencils and unzip the .vssx files into your My Shapes folder (visio_status reports the exact path, typically Documents\My Shapes):

• Azure (official icons): Azure architecture icons — Microsoft now publishes SVGs; for ready-made Visio stencils use the actively maintained community packs below.

• Azure (community .vssx packs): Microsoft Integration and Azure Stencils Pack (Sandro Pereira, includes MIS Azure Stencils.vssx and many more) or Azure-Design (David Summers).

• AWS: AWS Architecture Icons — the asset package includes Visio-compatible formats; community .vssx conversions are also linked from that page.

open_stencil("azure") fuzzy-matches any .vssx/.vss file under My Shapes, and find_masters("virtual machine") searches inside whatever is open.

Smoke test

Verifies the full pipeline end-to-end (launches Visio, builds a small styled flowchart, auto-lays it out, exports a PNG, saves/reopens the .vsdx):

uv run python scripts/smoke_test.py

Register with Claude Code

claude mcp add visio -- uv --directory C:\tools\visio_mcp run visio-mcp

Then ask Claude something like: "Draw a 5-step login flowchart in Visio and show me the result."

Tools

Coordinate system: inches, origin at the page bottom-left, y grows upward, and drop coordinates are the shape's center. Rough placement is fine — finish with auto_layout. The default page is US Letter (8.5×11): call set_page_size first for wide architecture diagrams, since PNG export crops to the page bounds.

Architecture

Claude (stdio) → FastMCP server (asyncio; no COM imports)
                    ↓ submits callables
                 ComWorker — single STA thread owns ALL COM objects
                    ↓
                 VisioClient — the only module that touches win32com
                    ↓
                 Visio.Application

COM objects are apartment-threaded, so every COM call is funneled through one dedicated STA worker thread (runtime.py); tool bodies just await results. This also serializes concurrent tool calls safely.

Development (any OS)

Unit tests run against a duck-typed fake of the Visio COM surface — no Windows needed:

uv sync
uv run pytest

Troubleshooting

Roadmap

• Agent skills encoding Azure/AWS diagram conventions (zones/containers, brand colors, icon naming)

• Optional HTTP transport to drive a Windows Visio box from another machine

• A scripts/install_stencils.py helper that downloads stencil packs into My Shapes