# VisioMCP — Enterprise Microsoft Visio MCP Server

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

```powershell
# 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"`:

```json
{
  "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):**
```powershell
[System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
```

**Python:**
```powershell
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):

```powershell
# 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`:

```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

```yaml
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

```powershell
# 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

```powershell
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:

```yaml
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