Metadata-Version: 2.4
Name: visio-mcp
Version: 0.1.1
Summary: MCP server exposing Visio COM automation to Claude
Project-URL: Repository, https://github.com/yushun/visio-mcp
Author: yushun
License-Expression: MIT
License-File: LICENSE
Keywords: automation,claude,diagram,mcp,visio
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business
Requires-Python: >=3.14
Requires-Dist: mcp[cli]>=1.27.0
Requires-Dist: pywin32>=311
Description-Content-Type: text/markdown

# visio-mcp

MCP server that exposes Microsoft Visio COM automation to Claude, enabling AI-driven diagram creation and manipulation.

## Features

- 22 built-in diagram types with correct Visio templates, stencils, and layout standards
- Batch shape drawing and connection — create complex diagrams in just a few tool calls
- Full Visio COM API coverage: documents, pages, shapes, connectors, stencils, export
- Coordinate-based precision drawing (rectangles, ovals, lines, Bezier curves, NURBS, splines)
- Export pages to PNG, SVG, JPG, etc.

## Requirements

- **Windows** with **Microsoft Visio** installed (Desktop version, not web-only)
- Python 3.14+

## Installation

```bash
pip install visio-mcp
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install visio-mcp
```

## Quick Start

### Configure in Claude Code

Add the following to your project's `.mcp.json` (or global MCP config):

```json
{
  "mcpServers": {
    "visio": {
      "command": "uv",
      "args": ["run", "--with", "visio-mcp", "python", "-m", "visio_mcp"],
      "env": {}
    }
  }
}
```

Then restart Claude Code. The Visio MCP tools will be available automatically.

### Run Standalone (for debugging)

```bash
uv run --with visio-mcp python -m visio_mcp
```

This starts the MCP server over stdio. Visio will launch automatically when the first tool is called.

## Usage

### Drawing Standard Diagrams (Recommended)

For any of the 22 supported diagram types, always start with `create_diagram`:

```
User: Draw a UML class diagram showing an Animal base class with Dog and Cat subclasses.
```

Claude will:

1. Call `create_diagram("class_diagram")` — creates a Visio document from the UML Class template with pre-loaded stencils. The response includes the full drawing standard (shapes, connectors, layout rules, and a working example).
2. Call `batch_draw_shapes(...)` — create all class shapes in one batch using the exact master names from the standard (e.g., `"Class"` from `"USTRME_M.VSSX"`).
3. Call `batch_connect_shapes(...)` — connect shapes using the correct connector type (e.g., `"Inheritance"` from `"USTRME_M.VSSX"` for UML generalization arrows).

### Free-form Drawing

For diagrams that don't fit a standard type, use `create_document()` and draw with primitive shapes:

```
User: Draw a custom infographic with rectangles and circles.
```

Claude will use `draw_rectangle`, `draw_oval`, `draw_line`, etc.

## Supported Diagram Types

| Category | Types |
|----------|-------|
| **UML** | Class, Sequence, Activity, State Machine, Use Case, Component, Deployment |
| **Flowchart** | Basic Flowchart (ISO 5807), Cross-Functional Flowchart (Swimlane) |
| **Process** | BPMN 2.0, Value Stream Mapping, Event-driven Process Chain (EPC) |
| **Data** | ERD (Crow's Foot), ERD (Chen), Data Flow Diagram (DFD) |
| **Infrastructure** | Network Topology, Azure Architecture, AWS Architecture, Kubernetes |
| **Other** | Org Chart, Cause & Effect (Fishbone), Block Diagram |

Use `list_diagram_types()` to query all available types at runtime.

## Available Tools

### Document Management

| Tool | Description |
|------|-------------|
| `create_diagram` | Create a new document from a standard diagram template (recommended) |
| `create_document` | Create a blank Visio document (free-form only) |
| `open_document` | Open an existing `.vsdx` / `.vsd` file |
| `save_document` | Save the active document |
| `save_document_as` | Save to a new file path |
| `close_document` | Close a document |
| `list_open_documents` | List all open documents |

### Page Operations

| Tool | Description |
|------|-------------|
| `list_pages` | List all pages in a document |
| `add_page` | Add a new page |
| `set_active_page` | Switch to a page by name or index |
| `delete_page` | Delete a page |

### Shape Creation

| Tool | Description |
|------|-------------|
| `batch_draw_shapes` | Create multiple shapes in one call (fastest) |
| `drop_shape` | Drop a stencil master shape at a position |
| `draw_rectangle` | Draw a rectangle |
| `draw_oval` | Draw an oval / ellipse |
| `draw_line` | Draw a line |
| `draw_polyline` | Draw a polyline or polygon |
| `draw_bezier` | Draw a Bezier curve |
| `draw_quarter_arc` | Draw a quarter-arc |
| `draw_spline` | Draw a smooth spline |
| `draw_nurbs` | Draw a NURBS curve |

### Connections

| Tool | Description |
|------|-------------|
| `batch_connect_shapes` | Connect multiple shape pairs in one call |
| `connect_shapes` | Connect two shapes with a connector |

### Shape Editing

| Tool | Description |
|------|-------------|
| `set_shape_text` | Set text content on a shape |
| `set_shape_format` | Set fill color, line color, font size, transparency, etc. |
| `move_shape` | Move a shape to a new position |
| `resize_shape` | Resize a shape |
| `delete_shape` | Delete a shape |
| `group_shapes` | Group multiple shapes together |

### Reading & Analysis

| Tool | Description |
|------|-------------|
| `list_shapes` | List all shapes with IDs, text, and positions |
| `get_shape_info` | Get detailed info about a single shape |
| `get_connections` | Get all connections on a page |
| `get_page_summary` | Get page statistics |
| `read_shape_data` | Read custom Shape Data properties |

### Stencils & Masters

| Tool | Description |
|------|-------------|
| `list_stencils` | List open stencils |
| `open_stencil` | Open a stencil file |
| `list_masters` | List all masters in a stencil |

### Diagram Standards

| Tool | Description |
|------|-------------|
| `list_diagram_types` | List all 22 supported diagram types |
| `get_diagram_standard` | Get full standard (shapes, connectors, layout, example) for a type |

### Export

| Tool | Description |
|------|-------------|
| `export_page_as_image` | Export a page to PNG, SVG, JPG, etc. |

## Coordinate System

Visio uses **inches** as the unit, with the origin at the **bottom-left** corner of the page:

- X increases to the right
- Y increases upward
- Default page size: 8.5 x 11 inches (US Letter)

## Example Prompts

Here are some things you can ask Claude with this MCP server:

- "Draw a flowchart for a user login process"
- "Create a UML class diagram for an e-commerce system with Product, Order, and Customer classes"
- "Draw a network topology diagram with 3 servers, a load balancer, and a firewall"
- "Create a BPMN process for employee onboarding"
- "Draw an ER diagram with Crow's Foot notation for a blog database"
- "Create an AWS architecture diagram with VPC, EC2, RDS, and S3"
- "Open my existing diagram at C:/docs/arch.vsdx and add a new component"
- "Export the current page as a PNG image"

## Troubleshooting

**MCP server won't start:**

1. Verify Visio is installed and can open normally
2. Test the server directly: `uv run --with visio-mcp python -m visio_mcp`
3. Verify pywin32 works: `python -c "import win32com.client; print('OK')"`

**Shape drop fails with "master not found":**

Always use `create_diagram(diagram_type)` instead of `create_document("")`. The standard template pre-loads the correct stencils. Check the master names in the returned standard.

**Connector arrows look wrong (e.g., UML inheritance missing triangle):**

Make sure `connector_master` and `connector_stencil` are specified in `batch_connect_shapes`. Using AutoConnect (empty connector) produces generic arrows without correct diagram-specific semantics.

## License

MIT
