papercanvas-mcp
PaperCanvas MCP server lets agents create, inspect, patch, lay out, validate, and render editable vector scientific figures via a versioned Figure IR.
Create a new figure IR file with path, figure ID, and canvas dimensions/margin.
Read the full IR (nodes, edges, groups, theme, canvas) plus blocking structural errors before patching.
Apply all-or-nothing semantic patch batches for nodes, edges, groups, styles, labels, and moves, with optional revision concurrency control.
Auto-layout figures using
linear-h,linear-v, orlayeredpresets.Render figures to SVG, PDF, and PPTX as true vector, editable output without modifying the IR.
Run FC001–FC008 quality lint checks for bounds, structure, overflow, overlap, font issues, arrows through nodes, and raster images.
Inspect all objects or detailed geometry/style/connections/groups for a specific object.
Run
doctorfor aggregated validation, lint, font coverage, renderability, and suggested fixes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@papercanvas-mcp Create a three-node ML pipeline figure and export it as SVG, PDF, and PPTX."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PaperCanvas
Agent-native scientific figure engine. Create, edit, and export publication-ready SVG, PDF & PPTX with MCP, CLI, and structured patches — the figure stays editable vector, never a bitmap.
A versioned Figure IR (JSON) is the single source of truth. Coding agents modify it through semantic patches — change one node without re-drawing the figure — and deterministic renderers produce true-vector output for papers, theses, and slides.
What it looks like
Real rendered output from the bundled examples (committed SVGs, shown inline):
Example | Figure | Sources |
Linear ML pipeline | ||
Video unlearning framework | ||
Multi-branch architecture with grouped heads |
Related MCP server: gitcad
Why PaperCanvas
Agent-native: seven MCP tools plus a CLI on one shared service layer — agents patch figures incrementally; untouched objects never move.
Figure IR as the single source of truth: SVG/PDF/PPTX are build products; nothing is hand-edited, everything is reproducible.
Transactional semantic patches: nine operations applied all-or-nothing with revision control — a failed patch leaves the file byte-identical.
Truly vector, truly editable: SVG
<text>, PDF with embedded TTF subsets, PPTX with native shapes/connectors — no rasterization anywhere.Deterministic: same IR + same fonts ⇒ byte-identical output; safe to re-export and diff.
Quality lint built in: FC001–FC008 (overflow, overlap, arrows through nodes, font substitution, …) with machine-readable JSON output.
60-second quickstart
pip install papercanvas # PyPI publication pending final approval
# for now, from a clone:
uv sync
papercanvas init figures.json --id demo
# 2. describe the figure as a patch (save as ops.json)
cat > ops.json <<'JSON'
{
"operations": [
{"op": "add_node", "node": {"id": "input", "type": "rounded_rect", "label": "Input Video"}},
{"op": "add_node", "node": {"id": "encoder", "type": "rounded_rect", "label": "Video Encoder"}},
{"op": "add_node", "node": {"id": "output", "type": "rounded_rect", "label": "Prediction"}},
{"op": "add_edge", "edge": {"id": "e1", "source": "input", "target": "encoder"}},
{"op": "add_edge", "edge": {"id": "e2", "source": "encoder", "target": "output"}}
]
}
JSON
papercanvas patch figures.json --ops ops.json
papercanvas layout figures.json --preset layered
papercanvas lint figures.json
papercanvas render figures.json --format all
# -> figures.svg figures.pdf figures.pptx
# 3. revise in place — rename ONE node and re-render, no rebuild:
echo '{"operations": [{"op": "update_label", "target": "output", "label": "Final Prediction"}]}' > round2.json
papercanvas patch figures.json --ops round2.json
papercanvas render figures.json --format allWindows PowerShell: replace the cat > ops.json <<'JSON' ... JSON block with
@' ... '@ | Set-Content ops.json (same JSON), and the last patch with
echo '...' | ... via a file — process substitution <(...) is bash-only.
Try it without writing anything:
uv run papercanvas build examples/basic_pipeline.json --format all
uv run papercanvas lint examples/basic_pipeline.jsonCLI
papercanvas init PATH --id FIGURE_ID [--width] [--height] [--margin]
papercanvas validate PATH
papercanvas patch PATH --ops ops.json # {"operations": [...], "expected_revision": N}
papercanvas layout PATH --preset linear-h|linear-v|layered
papercanvas lint PATH [--min-font-size PT] [--format text|json]
papercanvas inspect PATH [OBJECT_ID] [--format text|json]
papercanvas render PATH [--format svg|pdf|pptx|all] [--out FILE]
papercanvas build PATH [--preset ...] [--format ...] # layout + render in one commandEvery mutating command is transactional: validation errors leave the file
byte-identical; successes bump revision by one.
MCP server (for coding agents)
papercanvas-mcp --root path/to/projectSeven tools: papercanvas_create, papercanvas_get, papercanvas_patch,
papercanvas_layout, papercanvas_render, papercanvas_lint,
papercanvas_inspect. All paths must stay inside --root; failures return
structured {"ok": false, "error": ...} so agents can self-correct. See
docs/mcp.md.
Codex / Claude Code / OpenCode
PaperCanvas speaks standard MCP stdio, so any MCP client works. Point the
client at papercanvas-mcp with the project directory as --root:
Claude Code:
claude mcp add papercanvas -- papercanvas-mcp --root .(or add the JSON below to.mcp.jsonin the project)Codex CLI: add to
~/.codex/config.toml:[mcp_servers.papercanvas]withcommand = "papercanvas-mcp",args = ["--root", "."]OpenCode: add to
opencode.json:"mcp": {"papercanvas": {"type": "local", "command": ["papercanvas-mcp", "--root", "."]}}
Generic stdio JSON (most clients accept this shape):
{
"mcpServers": {
"papercanvas": {
"command": "papercanvas-mcp",
"args": ["--root", "."]
}
}
}The Agent Skill at
skills/papercanvas/SKILL.md (bundled inside
the wheel at papercanvas/skills/SKILL.md) teaches agents the full
workflow. Verification scope: all tool behavior is covered by real-protocol
tests (tests/test_mcp_e2e.py,
tests/test_mcp_stdio.py); the third-party client
UIs themselves were not exercised in this project's environment.
Install as a DSH plugin
PaperCanvas is also a DeepSeek Harness plugin — the seven tools surface directly inside DSH sessions:
dsh plugin --profile <profile> add github:HarryHeYu/figcraftThe plugin is a thin adapter over the papercanvas CLI (which must be
installed — from this repository until the PyPI publication). Verified
channels, same discipline as dsh-sessionflow:
DSH | install resolves | DSH loads it | tool call answered |
| ✅ | ✅ | ✅ |
| ✅ | ✅ | ✅ |
| ✅ | ✅ | ✅ |
| ✅ | ✅ | ✅ |
Cold-start CI: cold-start-figcraft — 5 matrix rows (install path × DSH channel), each proving install → bundle → prepare → profile layer → a real bridge call into the engine.
The Figure IR in one minute
Copy-paste this into quickstart.json — it validates and renders as-is:
{
"schema_version": "0.1",
"id": "method_pipeline",
"revision": 1,
"canvas": {"width": 100, "height": 40, "unit": "mm", "margin": 4},
"theme": {"font_family": "Arial", "font_size_pt": 8, "palette": {}},
"nodes": [
{
"id": "input",
"type": "rounded_rect",
"label": "Input Video",
"x": 8, "y": 13, "w": 34, "h": 14,
"style": {"fill": "#E8F0FE", "stroke": "#4275C4"}
},
{
"id": "encoder",
"type": "rounded_rect",
"label": "Video Encoder",
"x": 58, "y": 13, "w": 34, "h": 14,
"style": {"fill": "#E5F4EC", "stroke": "#418968"}
}
],
"edges": [
{
"id": "e1",
"source": "input",
"target": "encoder",
"source_port": "right",
"target_port": "left",
"style": {"stroke": "#444444", "arrow": "end"}
}
],
"groups": []
}uv run papercanvas validate quickstart.json # -> valid
uv run papercanvas render quickstart.json # -> quickstart.svgCapabilities & limitations
Figure IR v0.1 supports boxes (rect / rounded_rect), port-annotated
edges with orthogonal routing, groups, palette-driven styling, auto-sizing,
layered/linear layouts, and FC001–FC008 lint. CJK labels are measured and
rendered with a system CJK font when one exists (FC007 reports the
substitution). The full IR reference is in
docs/figure-ir.md.
Naming (final decision)
Surface | Name |
GitHub repository |
|
PyPI package |
|
CLI |
|
MCP server & tool prefix |
|
Python import |
|
Documentation
Changelog · milestone history in PROJECT-PLAN.md
Contributing
Issues and PRs welcome — see CONTRIBUTING.md. Security reports: SECURITY.md.
Roadmap
v0.2: obstacle-aware routing everywhere, broader CJK font fallback, two-column paper presets, visual regression baselines
later: additional figure types, web canvas exploration
License
Available Tools
8 toolspapercanvas_createC
Create a new figure IR file. Returns the path and initial revision.
Inputs: path (required), figure_id (required), width, height, +1 more.
papercanvas_doctorB
Aggregated quality diagnosis: hard validation, FC001-FC008 lint, font coverage/substitution, renderability per format. Returns findings classified as blocking / advisory / environment, with suggested patches for fixable issues. Read-only.
Inputs: path (required).
papercanvas_getA
Read the full figure IR (nodes, edges, groups, theme, canvas) plus hard_errors — the list of structural problems that block render/patch. Call this before patching.
Inputs: path (required).
papercanvas_inspectA
Inventory of all objects (ids, kinds, labels), or full detail for one object_id (geometry, style, connected edges, groups). Read-only.
Inputs: path (required), object_id.
papercanvas_layoutA
Arrange nodes (preset: linear-h | linear-v | layered) and commit the coordinates to the IR; revision increments by 1. Cycles are hard errors.
Inputs: path (required), preset.
papercanvas_lintA
Run quality checks FC001-FC008 (canvas bounds, structure, text overflow, overlap, font size, arrows through nodes, font substitution, raster images). Returns findings with rule_id/severity/object_id; severity 'error' means fix before delivering. Read-only.
Inputs: path (required), min_font_size_pt.
papercanvas_patchA
Apply a batch of semantic operations in ONE all-or-nothing transaction: add_node, remove_node (+remove_edges:true), update_node, set_style, add_edge, remove_edge, add_group, update_label, move_node. On success the revision increments by 1; on failure nothing changes. Pass expected_revision for optimistic concurrency.
Inputs: path (required), operations (required), expected_revision.
papercanvas_renderA
Render the figure to svg / pdf / pptx (a list, e.g. ['svg','pdf','pptx']). Output files are written next to the IR and are true vector + editable. Strictly read-only on the IR.
Inputs: path (required), formats.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct roles: create/get/patch mutate or read the IR, inspect inventories objects, layout arranges nodes, render exports files. The main ambiguity is between doctor and lint, since doctor aggregates lint results along with validation and renderability, and between get and inspect for read operations. Descriptions help, but an agent may still hesitate over doctor vs lint in particular.
All tools use the same papercanvas_ prefix and snake_case convention. The action words are predictable and readable, and there is no mixing of camelCase or unrelated naming styles.
Eight tools is a well-scoped set for a figure IR editor, covering creation, inspection, mutation, layout, quality checks, and rendering. Each tool earns its place without excessive surface area.
The surface covers the core lifecycle: create, read, inspect, patch, layout, lint/diagnose, and render. A dedicated delete/remove-file operation is missing, and theme-level editing is only indirectly covered, but these are minor gaps that agents can work around.
Maintenance
Related MCP Connectors
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Design canvas for agents: create, edit, render and export Figma-shaped designs over MCP.
Immutable agent diagrams: create, edit, validate and render versioned diagrams over MCP.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control Inkscape for vector graphics editing via MCP tools.102MIT

gitcadofficial
AlicenseNot gradedqualityDmaintenanceEnables agents to create and manipulate 3D CAD models using natural language via MCP, with git-based versioning and manufacturing output generation.2Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, inspect, validate, and export SVG designs using Inkscape CLI through MCP tools.2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to create, inspect, edit, render, and export SVG/Inkscape documents through typed drawing tools, with a deterministic offline backend and an optional bridge to a locally running Inkscape instance for limited live editing and snapshots.5BSD 3-Clause