Pencil MCP

Connected service reference

The Pencil field guide.

Nine MCP tools for reading, shaping, validating, and exporting .pen design files—explained as practical decisions, not protocol trivia.

Status  connected
Active filepencil/cards.pen
SelectionpUi7d · Card System
SchemaDocument 2.14
Verified2026-07-20

01 / Mental model

It is a tool surface, not a REST API.

Each “endpoint” below is an MCP tool call with a JSON argument object. The host handles transport, authentication, and response envelopes; you choose the right tool and provide valid arguments.

!
Never read .pen files with ordinary file tools.They are encrypted. Use Pencil’s inspection tools to understand them, and Pencil’s design tool to change them.
01 — ORIENT

Ask what is open.

Start with get_editor_state. It reveals the active file, selection, reusable components, and—when requested—the schema required for safe edits.

02 — ACT

Read before writing.

Use targeted reads, variables, layout snapshots, and screenshots. Only then use batch_design for small, coherent mutations.

03 — VERIFY

Structure, then pixels.

Use snapshot_layout for clipping and geometry. Use screenshots sparingly for color, type, alignment, and visual fidelity.

02 / Tool index

Choose by intent.

Search by tool name, task, or argument. Open any row for its request shape and a copyable example grounded in the connected workspace.

Showing 9 tools

03 / Workflows

Useful sequences beat isolated calls.

A good Pencil session is a short loop: orient, inspect, act, verify. These recipes show the smallest dependable sequence for common jobs.

Map the canvas without drowning in data.

Start broad, then descend only into the nodes that matter. Low read depths keep responses legible and reduce stale assumptions.

01Orientget_editor_state with the schema on your first call.
02List rootsbatch_get with readDepth: 1.
03Read tokensget_variables before interpreting variable references.
04Drill downRead selected IDs together; avoid one request per node.

Change one coherent section at a time.

Pencil is multiplayer. Re-read the target before editing, use a placeholder while constructing root frames, and verify immediately after each section.

01Load guidanceget_guidelines for the matching task.
02Inspect targetRead its structure, variables, and reusable components.
03MutateUse a small batch_design script with named nodes.
04VerifySnapshot layout first; screenshot only when visual judgment is needed.

Separate structural faults from visual faults.

Clipping and bounds are cheap to inspect as data. Color, typography, and optical alignment require a rendered image.

01Scansnapshot_layout with problemsOnly: true.
02LocateRead the affected node and its direct parent.
03RepairUpdate sizing or layout directly—do not rebuild the tree.
04ConfirmRepeat the problem scan, then take one focused screenshot.

Export when fidelity matters; inspect when semantics matter.

HTML export is a useful artifact, not a substitute for understanding component intent. Variables and node structure still inform maintainable production code.

01Choose nodesExport only the frames or components you need.
02Capture tokensMap Pencil variables to the codebase’s design tokens.
03ExportUse export_html or export_nodes to a deliberate output path.
04ValidateCompare implementation and source screenshots in context.

04 / Connection report

Tested against the live editor.

These checks used the active cards.pen document. Read-only calls were preferred; write and export probes were kept non-destructive.

●get_editor_stateActive file, selection, 34 components, and schema returned.
●get_guidelinesGuide and style catalogs returned; Code guide loaded.
●get_variablesLive token definitions returned from the active file.
●batch_getTop-level canvas nodes and system metadata returned.
●snapshot_layoutProblem-only structural scan returned clipped-node locations.
●get_screenshotFocused render probe completed on a reusable component.
●batch_designNon-mutating script probe completed without changing the document.
●export_nodesTemporary PNG export probe completed.
●export_htmlTemporary HTML + CSS export probe completed.
Connected documentcards.pen
Selected frameCard System
Reusable components34 discovered
Tool availability9 of 9 connected

05 / Guardrails

The expensive mistakes are predictable.

Most failures come from stale context, unsupported schema guesses, overly broad reads, or treating a collaborative canvas like a static file.

× FILE ACCESS

Do not grep a .pen.

The format is encrypted. Pencil MCP is the supported read/write boundary.

× SCHEMA GUESSING

Do not invent properties.

Call editor state with the schema, then use only supported Pencil values—not CSS assumptions.

× STALE STATE

Do not overwrite collaborators.

Re-read before edits. If a node moved or changed, inspect again instead of recreating it.

× DATA FLOODS

Do not read everything deeply.

Begin at depth 1–3, group node IDs into a single call, and descend deliberately.

× BLIND MUTATION

Do not batch a whole redesign.

Keep each design script small and coherent. Verify the completed section before continuing.

× SCREENSHOT SPAM

Do not use pixels for geometry.

Layout snapshots answer structural questions faster; screenshots are for visual fidelity.

06 / Iterate & deploy

One file. One durable URL.

Edit index.html, test locally, then deploy the folder again. Cloudflare Pages updates the project while preserving its production address. 

npx wrangler pages deploy . \
  --project-name pencil-mcp-field-guide