JSON Canvas MCP Server

A Model Context Protocol (MCP) server implementation that provides tools for working with JSON Canvas files according to the official specification. This server enables creating, modifying, and validating infinite canvas data structures.

Overview

The JSON Canvas MCP server provides a complete implementation of the JSON Canvas 1.0 specification, enabling:

Creation and manipulation of infinite canvas data
Support for all node types (text, file, link, group)
Edge connections with styling and labels
Validation against the specification
Configurable output paths

Components

Resources

The server exposes the following resources:

canvas://schema: JSON Schema for validating canvas files
canvas://examples: Example canvas files demonstrating different features
canvas://templates: Templates for creating new canvases

Tools

Node Operations

create_node
- Create a new node of any supported type
- Input:
  - type (string): Node type ("text", "file", "link", "group")
  - properties (object): Node-specific properties
    - Common: id, x, y, width, height, color
    - Type-specific: text, file, url, etc.
- Returns: Created node object
update_node
- Update an existing node's properties
- Input:
  - id (string): Node ID to update
  - properties (object): Properties to update
- Returns: Updated node object
delete_node
- Remove a node and its connected edges
- Input:
  - id (string): Node ID to delete
- Returns: Success confirmation

Edge Operations

create_edge
- Create a new edge between nodes
- Input:
  - id (string): Unique edge identifier
  - fromNode (string): Source node ID
  - toNode (string): Target node ID
  - fromSide (optional string): Start side ("top", "right", "bottom", "left")
  - toSide (optional string): End side
  - color (optional string): Edge color
  - label (optional string): Edge label
- Returns: Created edge object
update_edge
- Update an existing edge's properties
- Input:
  - id (string): Edge ID to update
  - properties (object): Properties to update
- Returns: Updated edge object
delete_edge
- Remove an edge
- Input:
  - id (string): Edge ID to delete
- Returns: Success confirmation

Canvas Operations

validate_canvas
- Validate a canvas against the specification
- Input:
  - canvas (object): Canvas data to validate
- Returns: Validation results with any errors
export_canvas
- Export canvas to different formats
- Input:
  - format (string): Target format ("json", "svg", "png")
  - canvas (object): Canvas data to export
- Returns: Exported canvas in requested format

Usage with Claude Desktop

Docker

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "jsoncanvas": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "canvas-data:/data",
        "mcp/jsoncanvas"
      ],
      "env": {
        "OUTPUT_PATH": "/data/output"
      }
    }
  }
}

UV

{
  "mcpServers": {
    "jsoncanvas": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/jsoncanvas",
        "run",
        "mcp-server-jsoncanvas"
      ],
      "env": {
        "OUTPUT_PATH": "./output"
      }
    }
  }
}

Configuration

The server can be configured using environment variables:

OUTPUT_PATH: Directory where canvas files will be saved (default: "./output")
FORMAT: Default output format for canvas files (default: "json")

Building

Docker Build

docker build -t mcp/jsoncanvas .

Local Build

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Run tests
pytest

Example Usage

Creating a Canvas

from jsoncanvas import Canvas, TextNode, Edge

# Create nodes
title = TextNode(
    id="title",
    x=100,
    y=100,
    width=400,
    height=100,
    text="# Hello Canvas\n\nThis is a demonstration.",
    color="#4285F4"
)

info = TextNode(
    id="info",
    x=600,
    y=100,
    width=300,
    height=100,
    text="More information here",
    color="2"  # Using preset color
)

# Create canvas
canvas = Canvas()
canvas.add_node(title)
canvas.add_node(info)

# Connect nodes
edge = Edge(
    id="edge1",
    from_node="title",
    to_node="info",
    from_side="right",
    to_side="left",
    label="Connection"
)
canvas.add_edge(edge)

# Save canvas
canvas.save("example.canvas")

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.