io.github.sshwarts/napkin

Napkin is a shared Excalidraw canvas for agent + human collaboration.

Why We Built It

I love using AI assistants for everyday tasks — design, programming, and brainstorming. I’ve always found visual thinking helpful, but there was a gap: I could describe something, and the agent could describe it back, but we couldn’t point to the same thing. What if my agent and I could share a whiteboard — where I draw, it responds, and we build together?

Napkin works with any MCP-capable agent. For true two-way canvas-to-agent, you'll also need a webhook.

Examples (all drawn by Perry the agent, with Napkin)

Brainstorming

Gaming

"Art" - Don't know why Perry invented a Platabird, but there you are.

Collaboration

What It Is

Napkin is an Excalidraw whiteboard connected to an MCP server. Any MCP-capable agent can read the canvas, draw on it, annotate it, animate it, and respond to what you draw — all while you interact with the agent through your normal channel (Slack, WhatsApp, Telegram, Terminal, or any MCP client).

The conversation stays in your channel. The canvas is pure whiteboard.

Quick Start

1) Start the MCP server

cd mcp
npm install
npm run build
npm start

Defaults:

• MCP HTTP: http://localhost:3003
• WebSocket: ws://localhost:3002

2) Start the browser UI

cd ui
npm install && npm run dev
# Open http://localhost:5173

3) Connect your agent

Napkin works with any MCP-capable agent. Add to your MCP client config:

{
  "napkin": {
    "type": "http",
    "url": "http://localhost:3003"
  }
}

Two-way vs one-way: MCP alone gives you agent→canvas (read, write, animate). For canvas→agent (the agent waking up when you draw something), you need a webhook receiver on your agent's side.

| Mode | What you get | Requires | |------|-------------|---------| | MCP only | Agent can read and write the canvas | Any MCP client | | MCP + webhook | Agent also reacts to human canvas activity | Webhook receiver (see below) |

4) Configure the webhook (two-way only)

When you draw on the canvas, Napkin POSTs a trigger to your agent's webhook endpoint. The agent wakes up, reads the canvas diff, and responds.

OpenClaw — built in. Set NAPKIN_TRIGGER_WEBHOOK in your environment and it routes automatically.

NanoClaw — add the webhook channel via PR #1488:

# .env additions
WEBHOOK_PORT=3200
WEBHOOK_LINKED_JID=<your channel JID>   # the chat where the agent should post

Then pass the webhook URL when starting your session:

start_session({
  session_id: "<your channel ID>",
  webhook_url: "http://localhost:3200/webhook"
})

Custom / other frameworks — any HTTP server that accepts POST /webhook with { message, sender? } JSON and forwards to your agent works fine.

Environment Variables

Common server variables:

• NAPKIN_TRANSPORT (http or stdio, default http)
• NAPKIN_MCP_PORT (default 3003)
• MCP_WS_PORT (default 3002)
• AGENT_TRIGGER_DEBOUNCE_MS (default 3000)
• NAPKIN_TRIGGER_WEBHOOK (optional global webhook URL)
• NAPKIN_COMPACT_TRIGGERS (true/false, default false)
• NAPKIN_TRIGGER_INCLUDE_CANVAS (true/false, default false)
• NAPKIN_SESSION_TTL_MS (default 7200000)
• NAPKIN_EXPORT_DIR (optional base dir for relative exports)
• ANTHROPIC_API_KEY (required for vision tools only

... View full README on GitHub