VisioMCP

Connect Claude directly to Microsoft Visio. Describe your infrastructure in plain English (or paste JSON/YAML/RVTools/Terraform exports) and get professional enterprise architecture diagrams — HLD, LLD, Network, DR, Backup, Cloud, and more — as VSDX + PDF + PNG + Word doc + BOM, all from a conversation.

---

What It Does

Capability	Detail
10 diagram types	HLD, LLD, Network, DR, Backup, Virtualization, Cloud, Physical, OpenShift, App Dependency
8 input parsers	JSON/YAML, natural language, RVTools XLS, Terraform tfstate, AWS/Azure/GCP exports, Redfish BMC, Ansible inventory
Vendor stencils	Auto-downloads VMware, Cisco, NetApp, HPE, Dell, Azure, AWS, GCP, Red Hat stencils
Export formats	VSDX, PDF, PNG, SVG, JPEG, EMF + Word HLD document + Excel BOM
35 MCP tools	Full control of Visio from Claude: create, edit, export, document
Dual transport	stdio (Claude Desktop / Claude Code) + SSE/HTTP (local reverse proxy)
Windows service	Run as a background service via pywin32

---

Prerequisites

Requirement	Version
Windows	10 / 11 / Server 2019+
Microsoft Visio	2016 / 2019 / 2021 / 365 (any edition)
Python	3.11+
Claude Desktop or Claude Code	Latest

---

Installation

# 1. Clone the repo
git clone https://github.com/omerbelsayed/visio-mcp.git
cd visio-mcp

# 2. Install (includes all dependencies)
pip install -e ".[dev]"

# 3. Run the setup wizard — verifies Visio is accessible and prints the Claude Desktop config
python -m visio_mcp setup

The setup wizard will:

• Confirm Python 3.11+
• Check Microsoft Visio is installed and launchable
• Tell you if your API key is configured
• Print the exact snippet to paste into claude_desktop_config.json

---

Claude Desktop Configuration

Open your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following under "mcpServers":

{
  "mcpServers": {
    "visiomcp": {
      "command": "python",
      "args": ["-m", "visio_mcp", "run", "--transport", "stdio"],
      "env": {
        "VISIOMCP_API_KEY": "your-secret-key-here"
      }
    }
  }
}

Restart Claude Desktop. You should see VisioMCP appear in the tools panel.

Generating the API key

Generate a random secret key using either of these commands:

PowerShell (no extra tools needed):

[System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

Python:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Either command prints a random string like k9Xv2mQpL8nRtY4wZjBcD1eAoHfIgNsU7CuWx0yVE3M=. Copy that output and use it as your key in both places below.

Setting the API key

Set it as an environment variable (never commit it to git):

# Permanent (user environment) — survives reboots
[System.Environment]::SetEnvironmentVariable("VISIOMCP_API_KEY", "paste-your-key-here", "User")

# Or for the current PowerShell session only
$env:VISIOMCP_API_KEY = "paste-your-key-here"

Then use the same key in claude_desktop_config.json:

"env": {
  "VISIOMCP_API_KEY": "paste-your-key-here"
}

Leave api_key: "CHANGE_ME" in config.yaml as-is — the server reads from the environment variable and ignores the placeholder.

---

Usage Guide

1. Describe your infrastructure in plain English

Just tell Claude what you have:

I have 3 ESXi hosts running 20 VMs. The VMs run SQL Server, IIS, and Apache.
Storage is a NetApp AFF A400 with 100TB. Network is Cisco Nexus 9000.
Create an HLD diagram.

Claude will parse your description, infer relationships, and generate a Visio diagram.

2. Paste a JSON/YAML inventory

virtual_machines:
  - hostname: web-01
    vcpu: 8
    ram_gb: 32
    hypervisor: vmware
    applications: [nginx, node]
  - hostname: db-01
    vcpu: 16
    ram_gb: 64
    hypervisor: vmware
    applications: [postgresql]

physical_servers:
  - hostname: esxi-01
    vendor: dell
    model: PowerEdge R750
    role: hypervisor

Then ask: "Create an LLD diagram from this inventory."

3. Upload an RVTools export

Tell Claude: "Parse this RVTools export and create a virtualization diagram." Then provide the .xlsx file path.

4. Use a Terraform state file

Parse my terraform.tfstate and show me a cloud architecture diagram.

5. Generate a full deliverable package

Generate a full package for the current diagram — VSDX, PDF, PNG, Word doc, and BOM.

This runs generate_full_package and produces all five files in one call.

---

Available MCP Tools

Document tools (9)

connect_visio, disconnect_visio, create_document, open_document, save_document, list_pages, add_page, select_page, undo

Stencil tools (4)

download_stencil, get_stencil, list_stencils, ensure_top_vendor_stencils

Parser tools (5)

parse_inventory (JSON/YAML/NL), parse_rvtools, parse_terraform_state, parse_ansible_inventory, get_inventory_summary

Generator tools (11)

create_hld, create_lld, create_network_diagram, create_dr_diagram, create_backup_diagram, create_virtualization_diagram, create_cloud_diagram, create_physical_diagram, create_openshift_diagram, create_app_dependency_diagram, generate_all_diagrams

Shape tools (6)

add_shape, connect_shapes, update_shape, delete_shape, find_shape, auto_layout

Export tools (3)

export_diagram, export_all_formats, generate_full_package

Document generation tools (3)

generate_hld_document, generate_bom, generate_stencil_report

---

Example Conversation

You: I have a 3-tier web application:
     - 2 NGINX load balancers (VM, 4 vCPU, 8GB)
     - 4 Apache web servers (VM, 8 vCPU, 16GB)
     - 2 PostgreSQL databases (VM, 16 vCPU, 64GB, replicated)
     All on VMware vSphere 8.0, shared storage on Pure Storage FlashArray.
     Create an HLD and then export as PDF and PNG.

Claude: [calls parse_inventory → create_hld → export_all_formats]
        Created HLD with 3 swimlanes (Network / Virtualization / Application).
        Exported: diagram.pdf, diagram.png
        Shapes placed: 12  |  Connectors: 9
        Stencils used: vmware.vsphere, purestorage.flasharray

---

Running as a Windows Service

# Install the service (run as Administrator)
python -m visio_mcp.service install

# Start
python -m visio_mcp.service start

# Stop
python -m visio_mcp.service stop

# Remove
python -m visio_mcp.service remove

The service runs the SSE transport on http://127.0.0.1:8000. For remote access, put nginx or Caddy in front with HTTPS and authentication.

---

Running Tests

pytest tests/unit/ -v
# Expected: 169 passed

Tests run without Visio using MockVisioEngine. No COM automation required for CI.

---

Configuration Reference

config.yaml — safe to commit, no secrets:

server:
  transports: [stdio, sse]
  sse_port: 8000
  api_key: "CHANGE_ME"      # override via VISIOMCP_API_KEY env var
  production_mode: false     # set true to reject CHANGE_ME key

stencils:
  base_path: ""              # defaults to stencils/ in project root
  max_age_days: 30
  max_concurrent_downloads: 5
  fallback_to_generic: true

visio:
  auto_launch: true
  default_template: "blank"
  units: "inches"
  reconnect_attempts: 3

logging:
  level: "INFO"
  file: "logs/visiomcp.log"
  max_bytes: 10485760        # 10 MB
  backup_count: 5

---

Architecture

Claude (stdio/SSE)
    │
    ▼
FastMCP Server (server.py)  ←── 35 MCP tools (visio_mcp/tools/)
    │
    ├── Parsers (visio_mcp/parsers/)
    │     JSON/YAML · NL · RVTools · Terraform · Cloud · Redfish · Ansible
    │
    ├── Generators (visio_mcp/generators/)
    │     HLD · LLD · Network · DR · Backup · Virtualization
    │     Cloud · Physical · OpenShift · AppDependency
    │
    ├── Stencil Manager (visio_mcp/stencils/)
    │     Auto-download · Cache · Registry · Vendor normalization
    │
    ├── Export Engine (visio_mcp/exporters/)
    │     VSDX · PDF · PNG · SVG · JPEG · EMF
    │
    ├── Doc Generator (visio_mcp/docs_gen/)
    │     Word HLD document · Excel BOM
    │
    └── Visio COM Gateway (visio_mcp/engines/visio_engine.py)
          Single ThreadPoolExecutor · CoInitialize · COM automation
          ↕ (test stub: MockVisioEngine)
          Microsoft Visio (COM)

Security notes:

• win32com is imported in exactly one file: visio_mcp/engines/visio_engine.py
• API key is read from VISIOMCP_API_KEY environment variable only
• SSE transport binds to 127.0.0.1 (localhost only)
• File-reading tools validate and resolve paths before opening

---

License

MIT