Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Whimsical MCP server

Vendor MCP
Open markdown

The Whimsical MCP connector routes your AI agent's tool calls to Whimsical's own MCP server through Scalekit. Each user signs in to Whimsical once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 18 tools.

Tools
18
What they doRead · write · destructive
7 · 6 · 57 read6 write5 destructive
Users sign in with
OAuth app
Scalekit's or your own

What you can do

  • Generate diagrams: create flowcharts, mind maps, and sequence diagrams from structured data, markdown, or Mermaid
  • Design wireframes: generate and edit wireframes with containers, buttons, inputs, and other UI elements
  • Create and edit files: make boards, docs, and folders, edit their contents, auto-layout flowcharts, and move files to trash
  • Find and read content: search the workspace, browse folders, and fetch boards or docs with an optional image snapshot
  • Work with comments: read, create, reply to, edit, resolve, and delete comment threads on boards and docs

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Whimsical MCP connection

    In AgentKit > Connections, create a Whimsical MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Whimsical MCP server, so you don't need to register an OAuth app.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'whimsicalmcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Whimsical MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'whimsicalmcp_file_tree',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • whimsicalmcp_comment_readRead all comment threads on a board item, including author, timestamp, and thread content.Read-only

    Comment Read

    Read all comment threads on a board item, including author, timestamp, and thread content.

    Inputs

    item_idstringrequired
    Board, doc, board-object, doc-block, or table-row id (short-id, base58, or UUID).
    cell_idstring
    Optional column id (short-id of the table column) to narrow results to a single cell. Only meaningful alongside a table-row `item_id`. Reuse the `:cell` value from a previous comment_read response.
    limitinteger
    Maximum number of threads to return (default 50).
  • whimsicalmcp_fetchFetch the content of a Whimsical board, doc, or folder by ID, optionally returning a PNG snapshot.Read-only

    Fetch

    Fetch the content of a Whimsical board, doc, or folder by ID, optionally returning a PNG snapshot.

    Inputs

    idstringrequired
    File or object ID (6-char short-id, UUID, or base58) from search results or a previous tool call, or a Whimsical link. A link to a doc block, board object, or board position reads just that part.
    board_idstring
    Parent board ID — required when fetching a table object. The table_id goes in 'id'.
    crop_idsarray
    Specific object IDs to crop the image to (image mode only).
    cursorstring
    Boards only: the cursor a previous board read gave, to read its next page. Repeat the same scope, select_kinds, grep_text and expand_groups with it.
    detailstring
    Detail level (boards only). "simple" (default): type, id, text only. "detailed": includes x, y, width, height, color, styling as `[props: {...}]` (deco, font_size, text_align, icon_name, icon_placement, state, named as edit takes them), and the board's color palette. Task rows surface assignee, tags, and description-present as inline markers in the text column: `[@name, #tag, 📝]`; wireframe options, dropdown values and form labels show as `[options: [...]]`, `[selected: "..."]` and `[label: "..."]` in both levels.one of simpledetailed
    expand_groupsboolean
    Show all objects flat instead of collapsing groups into summaries (boards only).
    formatstring
    Docs only. "ednl" (default): each block as hiccup. "markdown": each block's text as markdown with tags for mentions, item links, highlights and comments, which update_block takes back unchanged; see how_to('doc').one of ednlmarkdown
    grep_textarray
    Filter to items whose text contains any of these terms (boards and docs, case-insensitive).
    imageboolean
    Return a rendered PNG image instead of text (boards only). Use scope, crop_ids, or viewport to crop.
    include_metadataboolean
    Include the file's creation and update timestamps and display names.
    limitinteger
    Max rows/blocks to return (default: 50 for boards, 200 for docs, max: 200). On a board, a collapsed group counts as one row, and a page ends early when its rows' connectors would pass the limit.
    scopestring
    IMPORTANT for editing: ID of a compound diagram (flowchart, mindmap, sequence diagram) to drill into. Returns the actual node/shape text instead of the board overview summary. You MUST use scope before find_replace — board overview shows summaries like 'Root (5 nodes)' that won't match actual text.
    select_idsarray
    Return only items with these IDs (boards and docs)
    select_kindsarray
    Filter by type (boards and docs). For boards: shape, note, text, icon, frame, link, task, table, attachment, image, w-annotation, sd-actor. Groups: flowchart, mindmap, wireframe, sequence-diagram, stack, section. For docs: block element tags (p, h1, h2, ul, ol, etc.), plus nest for nested files (boards, docs, folders) embedded in the doc.
    spatialboolean
    Include spatial annotations (boards only, requires detail: detailed). Default: false.
    viewportobject
    Bounding box in board coordinates to crop the image to (image mode only).
  • whimsicalmcp_file_treeBrowse the workspace file hierarchy to list folders, boards, and docs with optional depth and type filtering.Read-only

    File Tree

    Browse the workspace file hierarchy to list folders, boards, and docs with optional depth and type filtering.

    Inputs

    depthinteger
    How many levels deep to show (default 2, max 5)
    filterstring
    Set to "teams" to list only the workspace's teams (name + id) without descending into files — use it to resolve a team name like "Trips" to its id. Ignored when folder_id is set.one of teams
    folder_idstring
    Folder, section, or team id (base58 or UUID) to browse — returns the file tree below it. Team ids come from filter="teams". Omit to see the whole workspace tree.
    include_metadataboolean
    Add creation/update metadata below browsed item rows. Workspace and section/team navigation headings are unchanged.
  • whimsicalmcp_get_board_itemsFetch board objects by file ID for rendering in the Whimsical widget.Read-only

    Get Board Items

    Fetch board objects by file ID for rendering in the Whimsical widget.

    Inputs

    fileIdstringrequired
    Board file ID (base58 or UUID)
    fieldsarray
    Object fields to include (omit for all). Lightweight: rect, objectType, text, fillColor, parentId, url. Heavy: gfx, rgfx, overlayGfx, hitboxes, shadowPathD.
    limitinteger
    Max objects per page (omit for all)
    offsetinteger
    Object offset for pagination (default 0)
  • whimsicalmcp_get_theme_dataFetch the board theme's dark color map for Whimbed rendering in the widget.Read-only

    Get Theme Data

    Fetch the board theme's dark color map for Whimbed rendering in the widget.

    Inputs

    fileIdstringrequired
    Board file ID (base58 or UUID)
  • whimsicalmcp_how_toLook up Whimsical-specific syntax, examples, and guides for creating diagrams and wireframes.Read-only

    How To

    Look up Whimsical-specific syntax, examples, and guides for creating diagrams and wireframes.

    Inputs

    domainstring
    Structured lookup that returns JSON (vs `topic` which returns markdown). Use {type:'icon', query:'database'} for ranked icon names with aliases, {type:'color', query?} for the canonical palette with aliases and descriptions, {type:'font-size'} for valid font sizes, {type:'kinds'} for the canonical add-op type list used by edit. When `domain` is provided, `topic` is ignored.
    topicstring
    Topic keyword (e.g. 'flowchart', 'table', 'colors') or search query
  • whimsicalmcp_add_board_contentAdd a diagram, sticky notes, a table or a wireframe to an existing board.Write

    Add Board Content

    Add a diagram, sticky notes, a table or a wireframe to an existing board. Create the board first with create_file(type:'board'). Steps/decisions/process → flowchart; hierarchy/outline → mindmap; actors exchanging messages → sequence_diagram; clustered short notes → sticky_notes; tabular data → table; UI screen → wireframe. These lay themselves out; for freeform shapes, text and connectors at absolute positions use edit's add operations instead. Mind maps: pass data.markdown directly (no how_to needed). Sequence diagrams: use data.diagram with arrow syntax (A -> B: msg) — no how_to needed for basic diagrams. Flowcharts: MUST call how_to('flowchart') first for the structured format. Wireframes: MUST call how_to('wireframe') first. To change an existing wireframe use wireframe_edit.

    Inputs

    board_idstringrequired
    The board to add it to
    typestringrequired
    What to addone of flowchartmindmapsequence_diagramsticky_notestablewireframe
    datastring
    Content payload, by type. Mindmap: {markdown: "Root\n- Child\n - Grandchild", layout?: "horizontal"|"vertical"} (indented bullets). Sequence diagram: {diagram: "A -> B: msg"}. Sticky notes: {notes: [{content, color?}]}. Table: {markdown: "| A | B |\n|---|---|\n| 1 | 2 |"} or {columns: ["A","B"], rows: [["1","2"]]}. Flowchart and wireframe: call how_to(type) for the format. Field names are snake_case.
    placementobject
    Position relative to a previous diagram's bbox (returned in every creation response). Use direction 'right' or 'below' to build grids. Mutually exclusive with x/y.
    titlestring
    Title for the content, e.g. a wireframe frame's. A mind map's is its root only when the markdown has several top-level items, or its top line is empty once a leading 'Title:' is dropped; otherwise the top line is the root.
    xnumber
    X position on board. Mutually exclusive with placement.
    ynumber
    Y position on board. Mutually exclusive with placement.
All 26 in Design