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.
- 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.
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.pngInstall it in a project:
npm i vsdx-kit # or: pnpm add vsdx-kit / yarn add vsdx-kitRequires Node.js 18 or newer.
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
| Option | Meaning |
|---|---|
-o, --output <file> |
Output file. The format follows the extension unless --format is given. Default: next to the input. |
-f, --format <fmt> |
vsdx (default for convert), png (default for preview), svg, drawio |
--page <n> |
Only page n (1-based) of a multi-page draw.io / JSON file |
--direction <dir> |
JSON input: right, down, left or up (overrides the file) |
--scale <n> |
PNG scale factor (default 2) |
--ai |
Send pictures / text to the VSDX.ai API (needs VSDX_AI_API_KEY) |
{
"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
| Field | Type | Notes |
|---|---|---|
title |
string | Drawn above the diagram; also the Visio page name |
direction |
right | down | left | up |
Main flow direction. Default right |
nodes |
Node[] | At least one |
edges |
Edge[] | Optional |
groups |
Group[] | Optional containers |
A JSON array of diagrams becomes a multi-page Visio document (example).
Node
| Field | Type | Notes |
|---|---|---|
id |
string | Unique, referenced by edges |
label |
string | Use \n for line breaks |
shape |
rect roundedRect ellipse circle diamond cylinder hexagon note actor text image |
Default roundedRect |
fill, stroke, fontColor |
#RRGGBB | #RGB | none |
Default palette per shape |
fontSize |
number (px) | Default 13 |
bold, dashed |
boolean | |
group |
string | Id of the containing group |
image |
string | For shape: "image": a data: URI (PNG, JPEG or SVG). In the CLI and MCP server a local file path also works |
width, height |
number (px) | Fix the size instead of fitting the text |
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.
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 }| Function | Returns |
|---|---|
jsonToVsdx(diagram | diagram[], opts?) |
Promise<Uint8Array> — .vsdx bytes |
drawioToVsdx(xml, { pages?: "all" | index, onWarning? }) |
Promise<Uint8Array> |
jsonToDrawio(diagram | diagram[], opts?) |
Promise<string> — editable draw.io XML |
toSvg(diagramOrDrawioXml, { page? }) |
Promise<string> |
toPng(diagramOrDrawioXml, { page?, scale?, background? }) |
Promise<Uint8Array> |
inspectVsdx(bytes) |
page names, shape / connector / glue / image counts |
parseDiagram(json), diagramSchema, diagramJsonSchema() |
validation (zod) and JSON Schema |
layoutDiagram, writeVsdx, renderSvg, renderPng, placedToDrawio |
lower-level building blocks working on absolute geometry |
opts accepts direction, nodeSpacing and layerSpacing. ESM only, with TypeScript types.
vsdx-kit mcp runs a local Model Context Protocol server over stdio. Tools:
| Tool | What it does |
|---|---|
create_vsdx_from_json |
Lays out a JSON diagram and writes a .vsdx (optionally a PNG preview). Returns the path and shape/connector counts. |
convert_drawio_to_vsdx |
Converts a .drawio file or XML string to .vsdx. |
ai_generate_diagram, ai_convert_image_to_vsdx |
Only when VSDX_AI_API_KEY is set — see below. |
Claude Code
claude mcp add vsdx-kit -- npx -y vsdx-kit mcpCursor (~/.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.
| Input | Preview | What it shows |
|---|---|---|
order-flow.json |
png | Flowchart with decisions, labels, a dashed branch |
zh-approval.json |
png | Chinese labels, top-down flow |
microservices.json |
png | Nested groups (containers), cylinders, hexagon, actor |
org-chart.json |
png | Org chart, custom colours, no arrowheads |
cloud-icons.json |
png | Embedded images (SVG icons) with captions |
multi-page.json |
png | Two diagrams → two Visio pages |
network-zh.drawio |
png | draw.io with a swimlane container, waypoints, Chinese text |
two-pages-compressed.drawio |
png | Compressed multi-page draw.io with embedded PNG/SVG images |
Ready-made .vsdx outputs are in examples/output. Regenerate with pnpm examples.
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 flowchartWith 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 (this repo) | VSDX.ai | |
|---|---|---|
JSON → native .vsdx |
✅ offline | ✅ |
draw.io → .vsdx |
✅ offline | ✅ |
| Picture / screenshot → editable Visio | — | ✅ image to Visio |
| Text / documents → diagram | — | ✅ |
| Online editor, revisions, team use | — | ✅ |
| CLI, Node library, local MCP server | ✅ | REST API + hosted MCP (developers) |
| Price | free, MIT | free credits, then paid plans |
- Microsoft Visio 2013 and later: files use the standard Visio 2013
.vsdxpackage 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
.vsdxfiles 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.
- 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.
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.
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- VSDX.ai — AI Visio generator: text, pictures and documents to editable
.vsdx. - LayerBack VSDX Viewer — free online viewer to check the files vsdx-kit writes when you don't have Visio.
- LayerBack — rebuilds a picture or PDF of a diagram as editable VSDX, PPTX, draw.io or SVG.
- awesome-visio — a curated list of Visio tools, libraries and resources.
vsdx-kit 是 VSDX.ai 团队开源的原生 Visio .vsdx 生成工具(命令行、Node.js 库与本地 MCP 服务),无需安装 Visio 或浏览器即可生成可编辑图表;VSDX.ai 的官方网站是 vsdx.ai。
- JSON 与 draw.io 离线转
.vsdx:用 JSON 描述节点、连线和分组(ELK 自动排版,连线吸附在形状上),或把多页.drawio离线转为原生.vsdx,也可导出 PNG、SVG、.drawio。 - 离线运行与中文友好:纯 Node.js(≥ 18)实现,无遥测无水印,内置思源黑体测量中日韩文字尺寸。
- 本地 MCP 服务:供 Claude Code、Cursor、Claude Desktop 等直接写出
.vsdx。 - 可选接入 VSDX.ai:设置
VSDX_AI_API_KEY可调用 API 将图片、文本转为图表;PDF、Word、Excel 或录音转流程图、泳道图、BPMN 可用在线 Studio。
需 Node.js 18 及以上,直接运行:
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安装到项目:
npm i vsdx-kit # or: pnpm add vsdx-kit / yarn add vsdx-kit接入本地 MCP(Claude Code,或写入 ~/.cursor/mcp.json、claude_desktop_config.json):
claude mcp add vsdx-kit -- npx -y vsdx-kit mcp{
"mcpServers": {
"vsdx-kit": {
"command": "npx",
"args": ["-y", "vsdx-kit", "mcp"]
}
}
}价格:vsdx-kit 开源免费(MIT);VSDX.ai:Free $0(注册赠送 20 积分,30 天过期,每次生成/转换消耗 10 积分),月付 Pro $20/月(300 积分/月)、Business $50/月(1000 积分/月)、Team $100/月(3000 积分/月),年付 Pro $120/年、Business $300/年、Team $600/年,积分包 300 积分 $20(90 天)/ 1000 积分 $50 / 3000 积分 $100(下载 .vsdx 需有效订阅或至少购买过一次积分包)。
相关链接:VSDX.ai 中文页 · 图片转 Visio · 开发者文档 · Awesome Visio
vsdx-kit は、VSDX.ai チームがオープンソースで公開しているネイティブ Visio .vsdx 生成ツール(CLI、Node.js ライブラリ、ローカル MCP サーバー)です。Visio やブラウザをインストールせずに編集可能な図表を生成できます。VSDX.ai の公式サイトは vsdx.ai です。
- JSON・draw.io からオフラインで
.vsdxへ変換:JSON でノード・エッジ・グループを記述(ELK による自動レイアウト、コネクタは図形に接着)、または複数ページの.drawioをオフラインでネイティブ.vsdxに変換できます。PNG、SVG、.drawioの書き出しにも対応しています。 - オフライン動作・日中韓(CJK)対応:純粋な Node.js(≥ 18)実装で、テレメトリや透かしはなく、内蔵フォント(Noto Sans SC / 源ノ角ゴシック)で中国語・日本語・韓国語テキストのサイズを計測します。
- ローカル MCP サーバー:Claude Code、Cursor、Claude Desktop などから直接
.vsdxを出力できます。 - VSDX.ai との任意連携:
VSDX_AI_API_KEYを設定すると API 経由で画像やテキストを図表に変換できます。PDF・Word・Excel・音声からのフローチャート、スイムレーン図、BPMN 生成にはオンライン Studio を利用できます。
Node.js 18 以上が必要です。そのまま実行する場合:
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プロジェクトにインストールする場合:
npm i vsdx-kit # or: pnpm add vsdx-kit / yarn add vsdx-kitローカル MCP に接続する場合(Claude Code、または ~/.cursor/mcp.json・claude_desktop_config.json に記述):
claude mcp add vsdx-kit -- npx -y vsdx-kit mcp{
"mcpServers": {
"vsdx-kit": {
"command": "npx",
"args": ["-y", "vsdx-kit", "mcp"]
}
}
}料金:vsdx-kit はオープンソースで無料(MIT)です。VSDX.ai:Free $0(登録時に 20 クレジット付与・30 日で失効、生成・変換ごとに 10 クレジット消費)、月額 Pro $20/月(300 クレジット/月)・Business $50/月(1000 クレジット/月)・Team $100/月(3000 クレジット/月)、年額 Pro $120/年・Business $300/年・Team $600/年、クレジットパック 300 クレジット $20(90 日間有効)/ 1000 クレジット $50 / 3000 クレジット $100(.vsdx のダウンロードには有効なサブスクリプション、または少なくとも一度のクレジットパック購入が必要です)。
関連リンク:VSDX.ai 日本語ページ · 画像を Visio に変換 · 開発者ドキュメント · Awesome Visio
MIT © 2026 TopLocalAI. Bundled Noto Sans SC fonts are under the SIL Open Font License 1.1.
