Skip to content
TopLocalAIPublic

About

Generate native Microsoft Visio .vsdx files from JSON or draw.io — no Visio, no browser. CLI, Node library and MCP server.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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.

npm CI License: MIT

English · 简体中文

A diagram generated by vsdx-kit from examples/microservices.json

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.

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
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)

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

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.

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 }
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.

MCP server (Claude, Cursor, other agents)

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 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

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.

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

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

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

  • 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

License

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

About

Generate native Microsoft Visio .vsdx files from JSON or draw.io — no Visio, no browser. CLI, Node library and MCP server.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages