obsidian-canvas-mcp

An MCP server for creating, reading, editing, converting, and exporting Obsidian Canvas files.

v0.1.0 — First stable release. Lightweight auto-layout, clean visual mode, and basic edge routing for Obsidian .canvas files.

This server works by reading and writing .canvas JSON files inside your Obsidian vault. It does not control the Obsidian UI. It can be called by Claude Code, Claude Desktop, Cursor, VS Code, or any MCP-compatible host.

Features

nFor detailed installation and configuration instructions, see Installation Guide and Development Roadmap.

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 |

Layout Support

Three auto-layout algorithms are available for create_canvas, markdown_to_canvas, and folder_to_canvas:

| Layout | Best for | |--------|----------| | grid | General notes, knowledge collections, multi-node organization | | roadmap | Learning routes, dev processes, release plans, sequential workflows | | hub | Project planning, brainstorming, knowledge maps, retrospectives |

For markdown_to_canvas only, two additional layouts are available:

| Layout | Best for | |--------|----------| | vertical | Simple step-by-step lists converted from Markdown | | mindmap | Markdown outlines and topic maps |

Visual Modes

visualMode is available on create_canvas:

| Mode | Behavior | |------|----------| | clean (default) | Fewer, larger cards with fewer edges. Ideal for user-facing canvases. Hub mode groups nodes by category and limits center connections. | | detailed | Preserves all nodes and edges exactly as provided. Suitable for detailed diagrams or testing. |

Automatic Features

• Node size estimation — width/height are estimated from text content (line count, bullet count, max line length). Minimum sizes are enforced to prevent tiny unreadable nodes.
• Edge routing — fromSide/toSide are calculated from node center points. All auto-generated edges use fromEnd="none", toEnd="arrow".
• Overlap fixing — lightweight correction pushes overlapping nodes apart after layout.
• Visual label detection — nodes with height <= 40 or keywords like "title", "phase", "stage" are treated as labels and excluded from layout.

Security

• Vault isolation — all file operations are confined to OBSIDIAN_VAULT_DIR.
• Path traversal prevention — paths containing .. or escaping the vault are rejected.
• Extension validation — .canvas, .md, and .json files are allowed; other extensions are blocked.
• Optional backup — canvas files are backed up before modification (OBSIDIAN_CANVAS_AUTO_BACKUP).
• Audit logging — all operations are recorded in logs/audit.log (OBSIDIAN_CANVAS_AUDIT_LOG).

Quick Start

1. Configure your MCP host

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": "/path/to/your/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": ["/absolute/path/to/obsidian-canvas-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_DIR": "/path/to/your/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"
      }
    }
  }
}

2. Set 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 |

3. Try it

Ask your MCP host to:

List all canvas files in my vault.

Create a canvas at "Projects/Alpha.canvas" with 4 nodes in a grid layout.

Convert this Markdown outline to a canvas:
# My Project
- Goal
- Feature A
  - Subtask 1
  - Subtask 2
- Risk

Layout Guide

grid — General collections

Uniform 3-column grid. Good for organizing notes, bookmarks, or reference materials.

A  B  C
D  E  F
G  H  I

roadmap — Sequential flows

S-curve layout, 4 nodes per row. Each row alternates direction so the flow wraps vertically.

Row 0 (L→R):  A → B → C → D
Row 1 (R←L):            H ← G ← F ← E
Row 2 (L→R):            I

Best for: learning paths, release plans, dev processes.

hub — Knowledge maps and planning

Radial layout with a center topic surrounded by category cards. In clean mode, the center connects only to category cards (not every detail node), and detail content is merged into category cards as bullet text.

           [Center Topic]

[Category A]    [Category B]
  - item 1        - item 1
  - item 2        - item 2
  - item 3        - item 3

Best for: project planning, brainstorming, retrospectives, summaries.

vertical — Simple lists (markdown_to_canvas only)

Nodes arranged top-to-bottom in a single column.

mindmap — Outline-to-map (markdown_to_canvas only)

Nodes arranged in a hierarchical outline layout. Root at top, children below.

Examples

Example 1: Create a roadmap

Create an Obsidian Canvas for "from idea to npm release".
Use layout="roadmap" with 9 steps.

Example 2: Create a project planning canvas

Create a Canvas for a local file organizer MCP project.
Use hub layout with visualMode="clean".
Use large category cards instead of one node per bullet.

Example 3: Convert a Markdown folder to a knowledge graph

Create a Canvas graph from Notes/Advanced.
Include subfolders and connect notes by wikilinks.

Example 4: Clean hub canvas

{
  "filePath": "Projects/Alpha.canvas",
  "nodes": [
    { "id": "center", "text": "本地文件整理助手 MCP", "width": 520, "height": 140 },
    { "id": "goals", "text": "项目目标\n\n- 整理本地文件\n- 查找重复文件\n- 生成整理建议" },
    { "id": "features", "text": "核心功能\n\n- 扫描文件夹\n- 识别文件类型\n- 批量移动文件\n- 生成报告" },
    { "id": "risks", "text": "风险问题\n\n- 误删风险\n- 大文件夹性能" }
  ],
  "edges": [
    { "fromNode": "center", "toNode": "goals" },
    { "fromNode": "center", "toNode": "features" },
    { "fromNode": "center", "toNode": "risks" }
  ],
  "layout": "hub",
  "visualMode": "clean"
}

Result: 4 nodes, 3 edges. Center connects only to category cards. Details are bullet text inside cards.

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

This project is tested with an external MCP JSON tester. To verify basic functionality:

# Run the layout test suite
npx tsx tests/layout.test.ts

# Run the obsidian compatibility test
npx tsx tests/obsidian/create-canvas-roadmap-routing.ts

Suggested test coverage:

• list_canvas_files — file discovery
• create_canvas — all layouts and visual modes
• read_canvas — roundtrip read/write
• add_text_node / add_file_node — incremental editing
• connect_nodes — edge creation and validation
• markdown_to_canvas — all 5 layout modes
• folder_to_canvas — folder and wiki-link modes
• export_canvas_to_markdown — node and relation export
• Path safety — traversal prevention, extension validation
• Visual layout — overlap prevention, node sizing

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.

License

MIT