vsdx-kit

Generate real, native Microsoft Visio .vsdx files — without Visio and without a browser.

Describe a diagram as JSON (or hand over a draw.io file) and get an editable Visio drawing with real shapes, glued connectors, text, containers and embedded images. CLI, Node.js library and MCP server for AI agents.

English · 简体中文

Preview of examples/microservices.json. The .vsdx it produces is examples/output/microservices.vsdx.

Why

• Native .vsdx — Open Packaging (OPC) files that Microsoft Visio opens as ordinary drawings: real shapes you can restyle, connectors glued to shapes (they follow when you move a box), text you can edit.

• Offline and headless — pure Node.js. No Visio, no Office, no headless Chrome, no network. Works in CI, servers and containers.

• Automatic layout — you list nodes and edges; ELK places them and routes orthogonal connectors. Groups become containers.

• draw.io → Visio — converts .drawio / diagrams.net files (plain or compressed, all pages) keeping geometry, colours, labels and embedded images.

• Built for AI agents — a tiny, documented JSON format with a JSON Schema, and a local MCP server so Claude, Cursor and other agents can write Visio files.

• CJK ready — Chinese/Japanese/Korean text is measured with a bundled Noto Sans SC font, so labels fit their shapes.

Related MCP server: Draw.io MCP Server

Quick start

npx vsdx-kit convert examples/order-flow.json -o order-flow.vsdx
npx vsdx-kit convert my-diagram.drawio            # → my-diagram.vsdx (all pages)
npx vsdx-kit preview examples/order-flow.json -o order-flow.png

Install it in a project:

npm i vsdx-kit        # or: pnpm add vsdx-kit / yarn add vsdx-kit

Requires Node.js 18 or newer.

CLI

vsdx-kit convert <input.json|input.drawio> [-o out.vsdx] [--format vsdx|png|svg|drawio]
vsdx-kit preview <input.json|input.drawio> [-o out.png]
vsdx-kit inspect <file.vsdx>        # page names, shape / connector counts
vsdx-kit schema                     # print the JSON Schema
vsdx-kit mcp                        # start the MCP server on stdio

JSON format

{
  "title": "Order flow",
  "direction": "right",
  "nodes": [
    { "id": "start", "label": "Order received", "shape": "ellipse" },
    { "id": "check", "label": "In stock?", "shape": "diamond" },
    { "id": "ship", "label": "Ship", "group": "wh" },
    { "id": "db", "label": "Orders DB", "shape": "cylinder", "group": "wh" }
  ],
  "edges": [
    { "from": "start", "to": "check" },
    { "from": "check", "to": "ship", "label": "yes" },
    { "from": "ship", "to": "db", "dashed": true, "arrow": "both" }
  ],
  "groups": [{ "id": "wh", "label": "Warehouse" }]
}

Diagram

A JSON array of diagrams becomes a multi-page Visio document (example).

Node

Edge — from, to (node ids), label, dashed, arrow (end default, start, both, none), color, optional id.

Group — id, label, fill, stroke, parent (id of an enclosing group, for nesting).

The full machine-readable definition is schema/diagram.schema.json (also exported as vsdx-kit/schema.json). Add "$schema" to your file for editor completion.

Library

import { writeFileSync, readFileSync } from "node:fs";
import { jsonToVsdx, drawioToVsdx, jsonToDrawio, toPng, toSvg, inspectVsdx } from "vsdx-kit";

const vsdx = await jsonToVsdx({
  title: "Hello Visio",
  nodes: [{ id: "a", label: "Hello" }, { id: "b", label: "Visio", shape: "ellipse" }],
  edges: [{ from: "a", to: "b" }],
});
writeFileSync("hello.vsdx", vsdx);

writeFileSync("flow.vsdx", await drawioToVsdx(readFileSync("flow.drawio", "utf8")));
writeFileSync("hello.png", await toPng({ nodes: [{ id: "x", label: "Preview" }] }));
console.log(await inspectVsdx(vsdx)); // { pages: [...], shapes: 2, connectors: 1 }

opts accepts direction, nodeSpacing and layerSpacing. ESM only, with TypeScript types.

MCP server (Claude, Cursor, other agents)

vsdx-kit mcp runs a local Model Context Protocol server over stdio. Tools:

Claude Code

claude mcp add vsdx-kit -- npx -y vsdx-kit mcp

Cursor (~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) and most other clients:

{
  "mcpServers": {
    "vsdx-kit": {
      "command": "npx",
      "args": ["-y", "vsdx-kit", "mcp"]
    }
  }
}

Then ask: “Draw our checkout flow as a Visio file in docs/checkout.vsdx.” Relative paths are resolved against the server's working directory.

Examples

Ready-made .vsdx outputs are in examples/output. Regenerate with pnpm examples.

Pictures, text and documents → Visio

vsdx-kit is the open format layer: it turns structured input into Visio. Turning a screenshot, whiteboard photo, PDF or a paragraph of text into a diagram needs AI, which vsdx-kit does not do offline. When you pass such a file, the CLI says so and exits.

For that, use VSDX.ai — the AI Visio generator from the same team (image to Visio, free credits for new accounts). With an API key (create one) vsdx-kit can call its public API for you:

export VSDX_AI_API_KEY=vsdx_...
npx vsdx-kit convert whiteboard.jpg --ai -o whiteboard.vsdx      # picture → editable Visio
npx vsdx-kit convert notes.md --ai -o notes.vsdx                 # text file → diagram
npx vsdx-kit generate "OAuth login sequence with refresh tokens" -o oauth.vsdx --type flowchart

With the key set, the MCP server also offers ai_generate_diagram and ai_convert_image_to_vsdx. These calls use credits on your VSDX.ai account. Without --ai / the key, vsdx-kit never contacts any server.

vsdx-kit vs VSDX.ai

Compatibility

• Microsoft Visio 2013 and later: files use the standard Visio 2013 .vsdx package format and open as normal drawings.

• LibreOffice Draw opens and exports them (tested with soffice --headless --convert-to png; result).

• draw.io / diagrams.net can import .vsdx.

• On macOS, where Visio is not available, you can view .vsdx files with vsdx.app or LibreOffice.

• Shapes use built-in geometry (no stencils needed); connectors use Visio's Dynamic Connector master and are glued (Connects) to their shapes. Text uses the Microsoft YaHei font name, which Visio substitutes where it is missing.

Limitations

• Auto-layout is ELK's layered algorithm with default-ish settings: good for flowcharts, pipelines, org charts and architecture overviews; dense graphs may get long detours. Use draw.io (or fixed coordinates via the lower-level API) when you need pixel control.

• No swimlane auto-layout yet (groups are laid out as containers).

• draw.io stencil shapes (mxgraph.* — AWS, Cisco, BPMN …) become labelled placeholders; remote image URLs are not downloaded.

• Images must be PNG, JPEG or SVG (SVG is rasterized).

• The npm package is ~15 MB because it bundles Noto Sans SC (used for text measurement and previews).

• No Visio → JSON/draw.io reader.

Privacy

No telemetry, no watermarks, no network access in offline mode. Only --ai / the AI MCP tools talk to vsdx.ai, and only when you set VSDX_AI_API_KEY.

Development

pnpm install
pnpm test        # vitest
pnpm build       # tsc → dist/
pnpm lint        # biome
pnpm examples    # regenerate examples/output and docs/examples
pnpm schema      # regenerate schema/diagram.schema.json

Related

• awesome-visio — a curated list of Visio tools, libraries and resources.

License

MIT © 2026 TopLocalAI. Bundled Noto Sans SC fonts are under the SIL Open Font License 1.1.