obsidian-canvas-mcp

An MCP server for creating, reading, editing, beautifying, and exporting Obsidian Canvas files inside a configured vault.

v0.2.1 — Natural language quality polish. Intent-aware layouts, semantic backbone edges, real Markdown checkboxes, stable text formatting, and improved edge labels.

This server reads and writes .canvas JSON files. It does not control the Obsidian UI. It can be called by Claude Code, Cursor, VS Code, or any MCP-compatible host.

Features

For detailed API reference, see docs/tool-scheme.md. For the development roadmap, see docs/roadmap.md.

Canvas Operations

| Operation | Tool | Description | |-----------|------|-------------| | List files | list_canvas_files | Find all .canvas files in the vault | | Create | create_canvas | Create a new canvas with nodes and edges | | Read | read_canvas | Read a canvas file and return all nodes/edges | | Add text node | add_text_node | Add a text node to an existing canvas | | Add file node | add_file_node | Add a file node referencing a .md file | | Connect nodes | connect_nodes | Add an edge between two nodes | | Markdown to Canvas | markdown_to_canvas | Convert a Markdown outline into a canvas | | Folder to Canvas | folder_to_canvas | Scan a folder of .md files and create a knowledge graph | | Export to Markdown | export_canvas_to_markdown | Export a canvas back to a Markdown outline | | Beautify | beautify_canvas | Apply layout, style, grouping, and edge cleanup to an existing canvas |

Layout Support

| Layout | Best for | |--------|----------| | grid | General notes, knowledge collections, multi-node organization | | roadmap | S-curve left-to-right — learning routes, dev processes, release plans | | hub | Radial knowledge map with category grouping | | vertical | Simple top-to-bottom list (markdown_to_canvas only) | | mindmap | Hierarchical outline layout (markdown_to_canvas only) |

Style Presets

8 deterministic color themes with role-based assignment: default, soft, vivid, roadmap, knowledge, project, review, dark.

Layout Presets

| Preset | Gap X | Gap Y | Best for | |--------|-------|-------|----------| | compact | 60px | 50px | Dense notes, many nodes | | balanced | 80px | 80px | Default, general purpose | | spacious | 140px | 120px | Presentations, readability |

Edge Modes

| Mode | Behavior | |------|----------| | normal | Keep all edges | | reduced | Keep only edges connected to high-degree (center/category) nodes | | bundled | Deduplicate edges, keeping only unique relationships |

Visual Modes

| Mode | Behavior | |------|----------| | clean (default) | Fewer, larger cards. Max 12 visual nodes. Excess content merged into category cards. | | detailed | Preserve all nodes and edges exactly as provided. |

v0.2.1 Highlights

• Intent-aware layout selection — layouts adapt to weekly plans, checklists, travel plans, finance dashboards, troubleshooting flows, roadmaps, architecture maps, review boards, and knowledge maps
• Improved visual hierarchy — hero cards, primary sections, warnings, tasks, and resources get differentiated sizing and placement
• Semantic backbone edges — clean diagrams keep meaningful relationships even in reduced or bundled edge mode
• Optional short edge labels — important semantic edges get brief labels like "下一步", "depends on", "routes to"
• Real Markdown checkboxes — generated checklists use - [ ] and - [x] that work in Obsidian
• Final Markdown sanitizer — removes pseudo-checkboxes (□, ☐, ✅, [ ]) and converts tables to bullet lists
• Reduced Markdown table usage — tables are avoided by default because Canvas text node rendering is inconsistent
• Improved overlap prevention — final layout pass resolves remaining node collisions
• Viewport-friendly layouts — non-flow canvases prefer horizontal distribution over infinite vertical stacking
• English-first tool descriptions — all MCP tool and schema descriptions are in clear, concise English

Installation

npm global

npm install -g @lifeng688/obsidian-canvas-mcp

npx (no install needed)

npx -y @lifeng688/obsidian-canvas-mcp

Configuration

Add the server to your MCP configuration (e.g., mcp.json for Claude Code):

Using npx (recommended):

{
  "mcpServers": {
    "obsidian-canvas-mcp": {
      "command": "npx",
      "args": ["-y", "@lifeng688/obsidian-canvas-mcp"],
      "env": {
        "OBSIDIAN_VAULT_DIR": "E:/Obsidian/Vault"
      }
    }
  }
}

Using built source:

git clone <your-repo>
cd obsidian-canvas-mcp
npm install
npm run build

{
  "mcpServers": {
    "obsidian-canvas-mcp": {
      "command": "node",
      "args": ["E:/obsidian-canvas-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_DIR": "E:/Obsidian/Vault"
      }
    }
  }
}

Windows npx:

{
  "mcpServers": {
    "obsidian-canvas-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@lifeng688/obsidian-canvas-mcp"],
      "env": {
        "OBSIDIAN_VAULT_DIR": "E:/Obsidian/Vault"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OBSIDIAN_VAULT_DIR | Yes | — | Absolute path to your Obsidian vault root | | OBSIDIAN_CANVAS_AUTO_BACKUP | No | true | Back up canvas files before modifying | | OBSIDIAN_CANVAS_AUDIT_LOG | No | true | Write audit log to logs/audit.log | | OBSIDIAN_CANVAS_MAX_NODES | No | 500 | Maximum nodes per canvas file |

Available Tools

list_canvas_files

List Obsidian Canvas files inside the configured vault. Use this tool when the user wants to find existing Canvas files, inspect available diagrams, or choose a Canvas to read, edit, beautify, or export.

Arguments: folderPath (optional), recursive (optional, default true)

create_canvas

Create a new Obsidian Canvas file with nodes, edges, layout, visual mode, and style options. Use this tool when the user asks to create a new diagram, roadmap, checklist board, knowledge map, project plan, travel plan, study plan, architecture map, or visual planning Canvas.

Key arguments: filePath, nodes, edges, layout, visualMode, stylePreset, layoutPreset, edgeMode, overwrite

read_canvas

Read an existing Obsidian Canvas file and return its nodes and edges. Use this before editing, connecting nodes, beautifying, exporting, or diagnosing a Canvas.

Arguments: filePath

add_text_node

Add a text node to an existing Obsidian Canvas file. Use for small incremental edits — adding a note, task card, warning, summary, or checklist item.

Arguments: canvasPath, text, x, y, width, height, color

add_file_node

Add a file node that references a Markdown file inside the vault. Use when the user wants a Canvas node linked to an existing note, document, or Markdown file.

Arguments: canvasPath, file, subpath, x, y, width, height, color

connect_nodes

Connect two existing canvas nodes with an edge. Use when the user wants to show a relationship, dependency, sequence, flow, reference, or cause-effect connection between existing nodes.

Arguments: canvasPath, fromNode, toNode, label, fromSide, toSide, allowDuplicate

markdown_to_canvas

Convert a Markdown outline or Markdown file into an Obsidian Canvas. Use when the user provides structured Markdown, headings, lists, checklists, notes, study outlines, project plans, or technical documentation and wants a visual Canvas.

Arguments: markdown or markdownPath, outputPath, layout, stylePreset, layoutPreset, edgeMode, overwrite

folder_to_canvas

Create a Canvas graph from Markdown files in a vault folder. Use when the user wants to visualize a folder of notes, build a knowledge graph, map project documents, or connect Markdown files by folder structure or wiki links.

Arguments: folderPath, outputPath, includeSubfolders, connectBy, layout, stylePreset, layoutPreset, edgeMode, overwrite

beautify_canvas

Apply layout, style, grouping, visual hierarchy, checkbox formatting, and edge cleanup to an existing Canvas. Use when the user says a Canvas is messy, too dense, too vertical, visually repetitive, hard to read, or needs a different style.

Arguments: canvasPath, outputPath, overwrite, stylePreset, layoutPreset, edgeMode, visualMode, preserveManualPositions, overrideColors, layout

export_canvas_to_markdown

Export an Obsidian Canvas into a readable Markdown outline with optional relations. Use when the user wants to turn a Canvas back into structured notes, documentation, summaries, project plans, or review material.

Arguments: canvasPath, outputPath (optional — if omitted, returns markdown string)

Natural Language Examples

Weekly life dashboard

"帮我做一个一周生活安排仪表盘，包含学习工作、运动、饮食、休息、家务、社交和个人成长。"

Uses a board-style layout with the title at the top and sections distributed horizontally.

Tokyo 3-day travel plan

"做一个东京三日游旅行计划，包含Day 1/2/3的大卡片，每天包含路线、交通、吃饭、预算和注意事项。"

Uses a timeline layout with sequential day cards and preparation notes.

npm package release checklist

"做一个npm包发布前的检查清单，包含测试、版本号、构建、发布和通知。"

Uses checklist formatting with real Markdown checkboxes (- [ ] / - [x]).

Local service connection troubleshooting

"做个本地服务连接失败的排错流程图，从检查服务启动开始，逐步排查端口、防火墙、环境变量、日志和权限。"

Uses a flow layout with labeled edges showing the decision path.

Node.js backend architecture

"做一个Node.js后端项目的架构Canvas，包含入口、路由、控制器、服务层、数据访问、配置、日志、测试和部署。"

Uses a layered architecture layout with dependency labels on edges.

Personal finance dashboard

"做个个人财务整理仪表盘，包含收入、固定支出、可变支出、储蓄目标和风险提示。"

Uses a dashboard layout with risk items highlighted.

Moving preparation checklist

"做一个搬家准备清单，包含证件、生活用品、电器和厨房用品的分类。"

Uses checklist formatting with categorized groups.

Docker learning roadmap

"做个Docker学习路线，从基础概念到镜像、容器、网络、Volume、Compose、Swarm、CI/CD集成。"

Uses a roadmap layout with sequential steps.

Limitations

• This server does not control the Obsidian UI. It reads and writes .canvas JSON files.
• Layout is lightweight and heuristic-based. Complex visual designs may need manual adjustment in Obsidian.
• Only files inside OBSIDIAN_VAULT_DIR are accessible.
• add_file_node only accepts .md files.
• The clean visual mode reduces node and edge counts for readability — it may not preserve every relationship you specify.
• beautify_canvas with preserveManualPositions=true preserves existing coordinates but may still apply overlap fixing.
• Canvas node text supports Markdown, but Markdown table rendering inside Canvas is inconsistent — bullet lists are preferred by default.
• Canvas checkbox support relies on standard Markdown task list syntax (- [ ] / - [x]) inside text nodes.
• Generated Canvas content follows the user's language. Tool descriptions and schema are English-first.

Safety

• Vault-relative paths only — all operations are confined to OBSIDIAN_VAULT_DIR
• Path traversal prevention — paths containing .. or escaping the vault are rejected
• Extension validation — only .canvas, .md, and .json files are allowed
• Stable error codes — FILE_NOT_FOUND, FOLDER_NOT_FOUND, FILE_ALREADY_EXISTS, INVALID_EXTENSION, PATH_OUTSIDE_WORKSPACE, NODE_NOT_FOUND, INVALID_ARGUMENT, INVALID_JSON, MAX_NODES_EXCEEDED, VAULT_NOT_CONFIGURED
• Audit logging — all operations logged to logs/audit.log
• Optional backup — canvas files backed up before modification

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in watch mode (development)
npm run dev

# Start the server
npm run start

# Launch MCP Inspector
npm run inspect

Testing

The v0.2.x release has been validated with automated regression tests covering Canvas creation, beautification, Markdown conversion, folder graph generation, Markdown export, editing regression, visual quality regression, and natural language quality checks.

# v0.2.0 test suite (147 assertions)
npx tsx tests/v02.test.ts

# Layout test suite (122 assertions)
npx tsx tests/layout.test.ts

License

MIT