Use Chalk with AI.

Chalk ships a bundled MCP server that exposes a set of chalk_* tools to any AI client that speaks the Model Context Protocol — Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code. Ask in natural language; the diagram lands as a real .chalk file in your library, ready to refine by hand or by chat.

Setup

Open Chalk's Settings → AI Integration. Pick your client, click Add, and the integration is wired up in one click — no editing JSON files, no quitting and relaunching.

For clients we don't have one-click support for, the same panel shows a copy-paste config snippet pointing at the bundled binary.

What to ask

Chalk doesn't need you to specify shapes or coordinates. Describe the diagram in plain English and Claude figures out the topology, edges, and labels. Mentioning the diagram type (flowchart, sequence, mind map, tree, class diagram) helps it pick the right tool.

Flowcharts

Decision trees, process flows, data pipelines. Auto-laid-out by dagre.

Use Chalk to draw a flowchart of our user signup flow in my "architecture" folder. Include validation, email confirmation, and the bounce case.
Sketch the data pipeline for our search service — ingest → parse → index → query — as a flowchart, top-to-bottom.
Create a flowchart showing the lifecycle of a Stripe payment, with branches for succeeded, failed, and disputed.

Sequence diagrams

Actors at top, messages between lifelines. Solid arrows for requests, dashed for responses.

Use Chalk to add an OAuth authorization-code flow as a sequence diagram in my "architecture" folder. Keep it high-level — User, Browser, Auth Server, Resource Server.
Create a sequence diagram showing how a Stripe webhook flows through our system and updates the order record.
Make a sequence diagram for our login flow with magic links.

Mind maps

Central topic with branches radiating outward. Good for brainstorming and topic decomposition.

Make a mind map of the topics for our next design review. Center node 'Q3 Review', branches for Auth, Search, Billing, and Onboarding.
Sketch the failure modes of our deployment pipeline as a mind map.
Brainstorm a mind map of side-project ideas for a long weekend.

Trees

Strict hierarchies. Org charts, taxonomies, file trees, decision trees.

Draw our team org chart as a tree. CEO at top, then Eng / Design / Sales, with reports under each.
Create a folder structure tree for a new Astro project.
Sketch a decision tree for "should I deploy on Friday?" with leaf nodes for yes/no outcomes.

Class & ER diagrams

Multi-row boxes (name / attributes / methods) with typed relationships.

Make a class diagram for User, Account, and Subscription. User has many Accounts; Account has one Subscription.
Draw an ER diagram for a blog: Post, Tag, Author, Comment.
Class diagram for an event sourcing model — Aggregate, Event, EventStore, Projection.

Iterating on an existing diagram

Once a diagram is on disk Claude can read it back, add pieces, and tweak.

Add a 'Forgot password' branch to the signup flowchart I just made.
Add a sticky note next to the Database in oauth-flow explaining the partition scheme.
In the search-pipeline diagram, move the parser box below ingest and re-layout.
Show me everything in my architecture folder, then summarize what oauth-flow contains.

Tips

Tell Claude which folder to put the diagram in. If you don't, it'll drop into MCP.
Close the file in Chalk before asking AI to edit it. Otherwise Chalk's autosave can race with the MCP write.
For dense diagrams, ask "keep it high level" or "max 6 nodes" — Claude will summarize.
If the auto-layout looks rough, ask for chalk_relayout — it re-runs the original layout from the spec stored in the file.
Manual edits stick: if you move a shape by hand, it stays where you put it. chalk_relayout is the one exception.

Tool reference

16 tools, grouped by what they do. You don't call these directly — Claude picks the right one based on your prompt.

Discover

chalk_list_folders: List folders in your Chalk library.
chalk_list_diagrams: List `.chalk` diagrams in a folder (or everywhere).
chalk_get_diagram_summary: Read a diagram and return shapes, edges, labels, colors.

Create

chalk_create_flowchart: Topology of nodes + directed edges; dagre auto-layout.
chalk_create_sequence_diagram: Actors with lifelines and messages between them.
chalk_create_mindmap: Radial layout from a tree of parent/child nodes.
chalk_create_tree: Strict hierarchical tree (org charts, taxonomies, file trees).
chalk_create_class_diagram: UML class / ER diagram with typed relationships.

Add to an existing diagram

chalk_add_shape: Drop a geo shape (rectangle, diamond, oval, etc.) at a specific spot.
chalk_add_arrow: Directional arrow; can bind to existing shape ids.
chalk_add_line: Free-positioned line — dividers, axes, separators.
chalk_add_note: Yellow sticky-note callout anchored near a target shape.
chalk_add_text: Free-floating text — titles, labels, legends.

Edit

chalk_update_node: Modify a single shape — label, color, size, position.
chalk_remove: Delete shapes; cascades to connected arrows.
chalk_relayout: Re-run the original layout from the spec stored in the file.

Privacy

The MCP server runs locally on your Mac as a sidecar binary. Your AI client (Claude, Cursor, etc.) connects to it directly. Prompts go to your AI provider under your own account and subscription — Chalk doesn't proxy or see them. See Privacy Policy for details.