Report Visio state: version, open documents and stencils, active page, the My Shapes folder path, and the built-in stencil library — including builtin_cloud_stencils, the Azure/AWS stencil files Visio ships with (openable by bare filename, no download needed). Launches Visio if it is not already running. Call this first.

Create a new drawing document in Visio.

Args: template: Visio template name or absolute path. Examples: 'BASFLO_U.VSTX' (Basic Flowchart, US units) or bare 'BASFLO' (units suffix added from measurement). Omit for a blank drawing. measurement: 'us' (inches) or 'metric' — used when template has no _U/_M suffix.

Open an existing Visio file (.vsdx/.vsd) for viewing or editing.

Save the active drawing. Pass an absolute path ending in .vsdx the first time; afterwards you can omit it to save in place.

Export a page as PNG and RETURN THE IMAGE so you can visually inspect the diagram. Use this after dropping/connecting/layout to verify the result and iterate.

Args: path: Output .png path; omit for an auto-named temp file. page: Page name; defaults to the active page.

Open a stencil (shape library) so its masters can be dropped.

Accepts a built-in name ('BASFLO_U.VSSX' basic flowchart, 'PERIPH_U.VSSX' peripherals...), an absolute path, or a fuzzy name matched against files in the My Shapes folder (where downloaded Azure/AWS stencil packs live).

Search masters (droppable shapes) in the open stencils by name substring. Omit query to list everything (capped at 100). Matching custom icons from the local icon folder are included too, marked with stencil '(local icon)'.

List the local custom-icon folder and the labeled image files in it.

Users manually download icons (e.g. from az-icons.com) and save them into this folder; each file's name without its extension is its label. Labels are discoverable via find_masters and can be placed with drop_shape('', x, y) when Visio has no built-in master. The folder defaults to ~/.visio-mcp/icons and moves with the VISIO_MCP_ICONS_DIR environment variable.

Drop one master onto the page. (x, y) is the shape CENTER in inches from the bottom-left. Returns the shape_id used by other tools.

Drop many masters in one call (preferred when building a diagram). Executed in a single undo scope. Returns a shape_id per item, in order.

Insert an external image (SVG, PNG, JPG, EMF, ...) onto the page as a shape — for custom icons that have NO Visio master (e.g. the newer Azure 'Subnet' glyph) or vendor logos.

Args: source: a LOCAL file path OR a direct http(s) IMAGE URL. A URL must point at the raw image bytes; icon web pages (single-page-app galleries such as az-icons.com) return HTML and are rejected with guidance — download the file in the browser and pass its path. x, y: shape CENTER in inches from the bottom-left. width_in / height_in: size in inches. Give just one to scale the other automatically and preserve the image's aspect ratio; omit both to keep the image's native size.

Prefer built-in masters (drop_shape) when Visio has the icon; use this for the gaps. Returns the shape_id.

Change a shape's text, position (center, inches), or size. Only the provided fields are changed.

Style a shape, connector, or container. Colors are hex like '#0078D4' (Azure blue) or '#FF9900' (AWS orange). Only the provided fields are changed. Works on containers too: theme-guarded cells are force- overridden, so recoloring a VNet/subscription boundary is supported.

Delete shapes (or connectors) by id.

Connect two shapes with a dynamic connector glued to both (Visio auto-picks the best sides and re-routes when shapes move).

Args: label: Optional text on the connector (e.g. 'Yes' / 'No'). route: 'right_angle' (default), 'straight', or 'curved'. line_pattern: 'dashed'/'dotted' are the convention for control-plane, auth, or reference flows in architecture diagrams. line_weight_pt: Thicker lines (e.g. 2) suit peering/trust boundaries. line_color: Hex like '#808080'.

List pages, add a page (optionally named), or activate a page by name.

Run Visio's automatic layout on the page — arranges shapes and re-routes connectors. Great after dropping shapes at rough positions. 'flowchart_tb' = top-to-bottom flowchart, '_lr' = left-to-right.

Resize the page. Do this BEFORE building a wide architecture diagram — the default page is US Letter (8.5 x 11 in) and export_page_png crops to the page bounds, so shapes placed beyond them are invisible.

Args: width_in / height_in: New page size in inches (e.g. 20 x 12 for a hybrid-cloud reference diagram). orientation: Print orientation; inferred from the size if omitted. fit_to_contents: True = shrink/grow the page to fit what's on it (alternative to explicit width/height).

Drop a text-only label (no border, no fill) — for diagram titles, legends, and callouts. (x, y) is the CENTER in inches. Size is estimated from the text if omitted. Auto-layout ignores unconnected text shapes.

Wrap existing shapes in a real Visio container (for VNets, VPCs, subnets, resource groups, trust zones). The container is sized around its members plus padding, and members MOVE WITH the container afterwards. Nest zones by creating inner containers first, then outer ones.

Args: label: Container heading text. member_ids: shape_ids to place inside. master: Optional container style name from Visio's built-in container stencil (defaults to the first available style).

To recolor the container afterwards (e.g. brand colors per zone), use style_shape on the returned shape_id — theme guards are overridden.

Add shapes to or remove shapes from an existing container.

Badge a container (zone) with a small header icon — e.g. the VNet icon on a VNet container, or the Subnet/Subscription icon on those boundaries.

Placement is deterministic: the icon is dropped just inside the chosen corner of the container (computed from the container's bounds — no manual coordinate math) and added as a container member so it moves with the zone. icon resolves to a built-in Visio master first (e.g. 'Virtual Networks'), then to a labeled image in the local icon folder (e.g. a saved 'subnet.svg' — see list_local_icons); errors with guidance when neither exists. Returns the badge's shape_id.

List everything on a page: shape ids, master names, positions (inches, center), sizes, text, connector endpoints (from_id/to_id), and container membership (container_ids). Call this to (re)discover shape ids, e.g. after open_document.