Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@visio-mcp Rename the 'Review' shape to 'Approved' and connect it to the 'Finalize' shape."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_shapesWindows, 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.
Related MCP server: Generative-UI-MCP
git clone https://github.com/isiec9ai/MCP.git visio-mcp
cd visio-mcp
py -m venv .venv
.venv\Scripts\pip install -e .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.exeClaude 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.
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.
Tool | What it does |
| Which Visio instance is attached, and what it has open |
| Open drawings (add |
| Pages, their size and shape counts |
| Shapes with the ids every editing tool needs, text, master, geometry |
| One shape in full: Shape Data, user cells, layers, hyperlinks, neighbours |
| The page as a graph, including connectors dangling at one end |
| Find shapes by text across every page |
| Masters available to drop, from the drawing and open stencils |
| A PNG of the page, returned inline so the model can look at it |
| Write a page to .png/.jpg/.svg/.emf/... on disk |
| Export the document to PDF |
Tool | What it does |
| Replace a shape's text |
| Drop a master, or draw a rectangle/ellipse/line, and get its new id |
| Glue a dynamic connector between two shapes |
| Move, resize or rotate — only the values you pass change |
| Delete a shape |
| Add a page |
| Set a Shape Data field, creating the row if needed |
| Find and replace across shapes |
| Select shapes in the window, to show you what it means |
| Write to disk (edits are in memory until you ask) |
| Undo, exactly as Ctrl+Z would |
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=1visio_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.
--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"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.
pip install -e ".[dev]"
pytestThe 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:
File | Role |
| The contract both backends implement |
| The live Visio instance, over COM |
| In-memory stand-in for tests and |
| Serialises calls onto one COM-initialised thread |
| Tool definitions and error mapping |
MIT
Add a page to a document.
Args: name: Name for the new page. Visio picks one if you omit it. document: File name or 1-based index. Omit for the active document.
Inputs: name, document. Returns: ok, page, action, detail, +3 more
Add a shape to a page and return its new id.
Prefer a master that the drawing already uses, so the new shape inherits the drawing's style; visio_list_masters shows what is available. Without a master you get a plain drawn shape.
Args: x: Centre of the shape, inches from the left edge. y: Centre of the shape, inches from the bottom edge. text: Text to put in the shape. master: Master name to drop, for example "Process". stencil: Stencil to look in if the master is not already available. width: Width in inches. Defaults to the master's own size, or 2. height: Height in inches. Defaults to the master's own size, or 1. primitive: Shape to draw when no master is given: rectangle, ellipse or line. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: x (required), y (required), page, text, +6 more. Returns: ok, page, action, detail, +3 more
Draw a dynamic connector from one shape to another.
The connector is glued to both shapes, so it reroutes itself when either one moves.
Args: from_shape_id: Shape the arrow leaves. to_shape_id: Shape the arrow points at. label: Optional text to put on the connector. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: to_shape_id (required), from_shape_id (required), page, label, +1 more. Returns: ok, page, action, detail, +3 more
Delete a shape from the page.
Deleting a box leaves its connectors behind as dangling lines, so delete those too, or check visio_list_connections afterwards.
Args: shape_id: Id from visio_list_shapes. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: shape_id (required), page, document. Returns: ok, page, action, detail, +3 more
Write a page to an image file on disk.
The extension picks the format; Visio handles .png, .jpg, .gif, .bmp, .tif, .svg and .emf.
Args: path: Destination file path. Relative paths resolve against the server's working directory. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document. max_pixels: Longest edge for raster formats.
Inputs: path (required), page, document, max_pixels. Returns: page, path, bytes, format, +1 more
Export a document to PDF.
Args: path: Destination .pdf path. document: File name or 1-based index. Omit for the active document. page: Page to export when all_pages is false. all_pages: Export every page rather than a single one.
Inputs: path (required), page, document, all_pages. Returns: page, path, bytes, format, +1 more
Read everything about one shape: text, geometry, Shape Data, layers, links.
shape_data keys are ShapeSheet row names, which is exactly what
visio_set_shape_data expects back.
Args: shape_id: Id from visio_list_shapes. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: shape_id (required), page, document. Returns: x, y, id, fill, +18 more
Read the page as a graph: which shape each connector runs from and to.
Connectors that are glued at only one end, or at neither, come back with null on the loose side, which is how you spot a broken diagram.
Args: page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: page, document. Returns: result
List the drawings open in Visio right now.
Args: include_stencils: Also list open stencil and template documents, which are normally hidden because they are not the user's drawing.
Inputs: include_stencils. Returns: result
List the shape masters available to drop with visio_add_shape.
With no arguments this covers the masters already used in the drawing plus every open stencil, which is usually what matches the drawing's existing style.
Args: stencil: Look inside this stencil instead, by file name Visio knows (for example "BASIC_U.VSSX") or a full path to a .vssx file. document: File name or 1-based index. Omit for the active document.
Inputs: stencil, document. Returns: result
List the pages of a document, with their size in inches and shape counts.
Args: document: File name or 1-based index. Omit for the active document.
Inputs: document. Returns: result
List the shapes on a page with their id, text, master and geometry.
This is the way to find the shape ids every editing tool needs. x and y are the centre of the shape in inches from the bottom-left of the page.
Args: page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document. include_connectors: Set false to hide connector lines and see only the boxes.
Inputs: page, document, include_connectors. Returns: result
Move, resize or rotate a shape. Only the values you pass are changed.
Args: shape_id: Id from visio_list_shapes. x: New centre x in inches from the left edge. y: New centre y in inches from the bottom edge. width: New width in inches. height: New height in inches. angle: New rotation in degrees, counter-clockwise. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: shape_id (required), x, y, page, +4 more. Returns: ok, page, action, detail, +3 more
Render a page to a PNG and return it, so you can look at the drawing.
Use this whenever layout, overlap or visual style matters; shape coordinates alone rarely tell you whether a diagram reads well.
Args: page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document. max_pixels: Longest edge of the image. Keep it modest unless you need to read small print.
Inputs: page, document, max_pixels.
Replace a substring in the text of every shape that contains it.
Args: find: Substring to look for. replace: Replacement text. page: Restrict to one page. Omit to cover every page. document: File name or 1-based index. Omit for the active document. match_case: Match case exactly instead of ignoring it.
Inputs: find (required), replace (required), page, document, +1 more. Returns: ok, page, action, detail, +3 more
Write the document to disk. Edits are in memory until this is called.
Args: document: File name or 1-based index. Omit for the active document. path: Save to this path instead of the document's own, leaving the original file untouched.
Inputs: path, document. Returns: ok, page, action, detail, +3 more
Find shapes whose text contains a substring, across every page.
Args: query: Substring to look for. document: File name or 1-based index. Omit for the active document. match_case: Match case exactly instead of ignoring it.
Inputs: query (required), document, match_case. Returns: result
Select shapes in the Visio window, to show the user what you mean.
This changes the selection and the page on screen but not the drawing.
Args: shape_ids: Ids to select. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: shape_ids (required), page, document. Returns: ok, page, action, detail, +3 more
Set a Shape Data field on a shape, creating the row if it is missing.
Args: shape_id: Id from visio_list_shapes. name: Row name, as shown in visio_get_shape's shape_data keys. Letters, digits and underscores only. value: Value to store. label: Display label shown in Visio's Shape Data window. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: name (required), value (required), shape_id (required), page, +2 more. Returns: ok, page, action, detail, +3 more
Replace the text of one shape.
Args: shape_id: Id from visio_list_shapes. text: New text. Use \n for a line break. page: Page name or 1-based index. Omit for the page on screen. document: File name or 1-based index. Omit for the active document.
Inputs: text (required), shape_id (required), page, document. Returns: ok, page, action, detail, +3 more
Check which running Visio instance is attached and what it has open.
Call this first, and again if another tool reports a lost connection.
Inputs: no named parameters. Returns: note, backend, version, connected, +5 more
Undo the last actions in Visio, exactly as Ctrl+Z would.
This undoes whatever is on top of Visio's undo stack, which may be the user's own last edit rather than yours.
Args: steps: How many steps to undo.
Inputs: steps. Returns: ok, page, action, detail, +3 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 22 tools
Most tools have clearly distinct purposes (shape editing, page rendering, document inspection, connector management), but visio_render_page and visio_export_page are close enough to require careful reading, and visio_list_shapes vs visio_search_text overlap slightly in discovery.
All tools follow a consistent visio_verb_noun snake_case pattern, such as visio_list_shapes, visio_add_shape, and visio_set_shape_text. Minor compound names like visio_set_shape_data still fit the same predictable convention.
With 22 tools, the surface is larger than a typical minimal MCP server, but the count is justified by covering document, page, shape, connector, selection, export, undo, and save operations without feeling bloated.
The tool set covers the main Visio workflow: inspecting, creating, editing, connecting, selecting, rendering, saving, and undoing. Missing operations like opening/creating documents or grouping shapes are notable but not critical for common automation tasks.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.