mcp-scapple

An MCP (Model Context Protocol) server for reading, writing, and rendering Scapple (.scap) files. Scapple is a brainstorming tool by Literature & Latte that stores diagrams as XML. This server enables AI assistants to work with Scapple files directly.

Features

• read-scapple: Parse a .scap file into structured JSON with notes, background shapes, note styles, and connections
• write-scapple: Create a .scap file from structured note data with automatic bidirectional connection management
• text-to-scapple: Convert indented text, bullet lists, or numbered lists into Scapple diagrams with automatic layout and optional themed rendering
• scapple-to-image: Render a .scap file to PNG with full theme support (background, colors, fonts, shadows, patterns)

Examples

You can use natural language to create and render diagrams:

"Make a brainstorm diagram about mobile app development with branches for design, backend, and testing"

"Render that diagram with a dark theme — navy background, dot pattern, no shadows"

Theme Options

The scapple-to-image and text-to-scapple tools accept an optional theme parameter with the following properties. All properties are optional — when omitted, values from the .scap file's settings are used first, then the defaults below.

Canvas

Property	Type	Default	Description
backgroundColor	string	#ffffff	Canvas background color (hex)
backgroundPattern	string	none	Pattern type: none, dots, grid, lines
patternColor	string	#cccccc	Pattern color (hex)

Notes

Property	Type	Default	Description
strokeColor	string	#cccccc	Note border color (hex)
strokeWidth	number	1	Note border width
borderRadius	number	8	Rounded note corner radius
shadowColor	string	#00000033	Shadow color (hex with alpha)
shadowEnabled	boolean	true	Enable/disable shadow
defaultFill	string	none	Default note fill color (hex)
defaultBorder	string	None	Default border style: Rounded, Square, Cloud, None

Text

Property	Type	Default	Description
defaultFont	string	Helvetica	Default font family
defaultFontSize	number	12	Default font size
defaultTextColor	string	#000000	Default text color (hex)
defaultAlignment	string	Center	Default text alignment: Left, Center, Right
noteXPadding	number	8	Horizontal padding inside notes

Connections

Property	Type	Default	Description
lineColor	string	#666666	Connection line color (hex)
lineWidth	number	1	Connection line width
arrowColor	string	#666666	Arrow color (hex)

Scapple File Settings

When rendering a .scap file, the following settings are read from the file and used as theme defaults (overridden by explicit theme parameters):

• BackgroundColor → backgroundColor
• DefaultTextColor → defaultTextColor
• DefaultFont (UISettings) → defaultFont
• NoteXPadding (UISettings) → noteXPadding

Per-note appearance settings (border color, weight, text color, fill, font, bold/italic) always take precedence over theme defaults.

Components

Path	Description
src/index.ts	MCP server entrypoint
src/types.ts	TypeScript type definitions
src/errors.ts	Custom error class hierarchy
src/lib/parser.ts	.scap XML to ScappleDocument parser
src/lib/builder.ts	ScappleDocument to .scap XML builder
src/lib/renderer.ts	SVG/PNG rendering pipeline
src/lib/layout.ts	Text-to-diagram automatic layout
src/lib/svg/	SVG generation modules (shapes, connections, text, defs)
src/tools/	MCP tool handlers
examples/	Rendered samples

Requirements

• Node.js 18+
• npm

Usage

Configure in Claude Code

claude mcp add --transport stdio --scope user scapple -- npx -y @binaryloader/mcp-scapple

4. Tool Usage

read-scapple — Read a Scapple file:

filePath: "/path/to/diagram.scap"

write-scapple — Create a Scapple file:

filePath: "/path/to/output.scap"
document: { notes: [{ x: 100, y: 100, text: "Hello" }] }

text-to-scapple — Convert text to diagram:

text: "Root Topic\n  Branch A\n    Leaf 1\n  Branch B"
filePath: "/path/to/output.scap"
renderImage: true

scapple-to-image — Render to PNG:

filePath: "/path/to/diagram.scap"
scale: 2
theme: { backgroundColor: "#1a1a2e", backgroundPattern: "dots", shadowEnabled: false }

License

This project is licensed under the MIT License - see the LICENSE file for details.