Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Whimsical MCP connector

OAuth 2.1/DCR DesignProductivityAI

Connect to Whimsical MCP. Create and edit flowcharts, mind maps, wireframes, and docs, and manage boards, comments, and workspaces from your AI workflows.

Whimsical MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “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. Authorize and make your first call

    Section titled “Authorize and make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_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)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'whimsicalmcp_list_workspaces',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Edit wireframe, comment — Reflow or edit Whimsical wireframe elements using operations or a flexbox layout tree
  • Search records — Search workspace files and content by name or full-text query
  • List workspaces — List all workspaces the authenticated user belongs to, including team IDs and member roles
  • To how — Look up Whimsical-specific syntax, examples, and guides for creating diagrams and wireframes
  • Get board items — Fetch board objects by file ID for rendering in the Whimsical widget
  • Wireframe generate — Generate a Whimsical wireframe with flexbox layout using containers, buttons, inputs, and other UI elements

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

whimsicalmcp_auto_layout # Re-arrange shapes on a Whimsical flowchart using the auto-layout engine, with connectors re-routed automatically. 4 params

Re-arrange shapes on a Whimsical flowchart using the auto-layout engine, with connectors re-routed automatically.

Name Type Required Description
board_id string required Board file ID
orientation string optional Layout direction (td=top-to-bottom, lr=left-to-right, bt=bottom-to-top, rl=right-to-left). Inferred from connector flow when omitted.
parent_id string optional Optional: scope layout to descendants of this object id (e.g. a group/container). Omit to lay out all root-level shapes on the file.
spacing string optional Spacing preset; defaults to 'default'.
whimsicalmcp_comment_edit # Create, reply to, edit, resolve, or delete comment threads on a Whimsical board or doc. 6 params

Create, reply to, edit, resolve, or delete comment threads on a Whimsical board or doc.

Name Type Required Description
action string required Which comment operation to perform.
cell_id string optional For create on a table cell: the column id (short-id of the table column). Combined with a table-row `item_id` to target a single cell. Reuse a `:cell` short-id from a previous comment_read response.
comment_id string optional For edit/delete: id of the specific comment to modify.
content string optional For create/reply/edit: markdown content for the comment.
item_id string optional For create: id of the board, doc, board object, or table row to attach the thread to.
thread_id string optional For reply/resolve/unresolve: id of the root comment of the thread.
whimsicalmcp_comment_read # Read all comment threads on a board item, including author, timestamp, and thread content. 3 params

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

Name Type Required Description
item_id string required Board, doc, board-object, doc-block, or table-row id (short-id, base58, or UUID).
cell_id string optional 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.
limit integer optional Maximum number of threads to return (default 50).
whimsicalmcp_create # Create a new Whimsical board, diagram, folder, or doc in the specified workspace or folder. 9 params

Create a new Whimsical board, diagram, folder, or doc in the specified workspace or folder.

Name Type Required Description
type string required What to create. Use 'board' for freeform/sketch layouts where you control absolute positions (ideal for recreating hand-drawn notes, whiteboards, or any visual layout). Use 'flowchart', 'mindmap', 'sequence_diagram', 'sticky_notes', or 'wireframe' for semantic diagrams that auto-layout.
board_id string optional Add to existing board. Omit to create new board. Required for wireframe.
data string optional Content payload. Board (freeform layout): {items: [{type:"text"|"shape"|"note"|"conn"|"icon"|"link", text, x, y, ...}], groups?: [...]}. Field names are snake_case: shape_type, from_id, to_id, temp_id, font_size, icon_name (NOT camelCase). For board items the `text` field accepts markdown (**bold**, *italic*, `code`, - bullet, 1. numbered, [label](url), # heading). URLs to Linear issues or GitHub issues/PRs render as inline badges; custom labels ([label](url)) aren't kept for these — use a bare URL. Keep one item per entity (one Linear issue, one card); put the formatting inside that item's text rather than splitting it across several items. Only emit conn items for arrows actually present in the source — do not invent connectors. Call how_to('board') for the full schema and examples. Mindmap: {markdown: "Root\n- Child\n - Grandchild"} (indented bullets). Flowchart/sequence_diagram: call how_to(type) for syntax. Wireframe: call how_to('wireframe') for flexbox DSL. Table: {markdown: "| A | B |\n|---|---|\n| 1 | 2 |"} or {columns: ["A","B"], rows: [["1","2"]]}.
parent_id string optional Folder or team id (base58) to create in. Find folder ids with file_tree, team ids with file_tree({filter:'teams'}), search, or list_workspaces. Defaults to the Private section.
placement object optional 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.
title string optional Title or name for the created item
workspace_id string optional Workspace ID (UUID). Use list_workspaces to see options. Defaults to most recently active workspace.
x number optional X position on board. Mutually exclusive with placement.
y number optional Y position on board. Mutually exclusive with placement.
whimsicalmcp_delete # Move a Whimsical file, folder, or doc to trash, restoring it later from the Whimsical UI. 1 param

Move a Whimsical file, folder, or doc to trash, restoring it later from the Whimsical UI.

Name Type Required Description
id string required Id of the file, folder, or doc to delete. Accepts UUID or base58 form (as returned by file_tree or search).
whimsicalmcp_doc_create # Create a new Whimsical document with optional markdown content. 4 params

Create a new Whimsical document with optional markdown content.

Name Type Required Description
data string optional Document content as a markdown string.
parent_id string optional Folder or team section ID to create in. Defaults to Private section.
title string optional Document title
workspace_id string optional Workspace ID (UUID). Use list_workspaces to see options. Defaults to most recently active workspace.
whimsicalmcp_edit # Edit a Whimsical board or doc by applying an array of add, update, or delete operations to its objects. 2 params

Edit a Whimsical board or doc by applying an array of add, update, or delete operations to its objects.

Name Type Required Description
id string required Board or doc ID (from create, fetch, or a previous tool response)
operations array required Array of operations to perform
whimsicalmcp_fetch # Fetch the content of a Whimsical board, doc, or folder by ID, optionally returning a PNG snapshot. 13 params

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

Name Type Required Description
id string required File or object ID (6-char short-id, UUID, or base58) from search results or a previous tool call
board_id string optional Parent board ID — required when fetching a table object. The table_id goes in 'id'.
crop_ids array optional Specific object IDs to crop the image to (image mode only).
detail string optional Detail level (boards only). "simple" (default): type, id, text only. "detailed": includes x, y, width, height, color, and the board's color palette. Task rows surface assignee, tags, and description-present as inline markers in the text column: `[@name, #tag, 📝]`.
expand_groups boolean optional Show all objects flat instead of collapsing groups into summaries (boards only).
grep_text array optional Filter to items whose text contains any of these terms (boards and docs, case-insensitive).
image boolean optional Return a rendered PNG image instead of text (boards only). Use scope, crop_ids, or viewport to crop.
limit integer optional Max objects/blocks to return (default: 50 for boards, 200 for docs, max: 200)
scope string optional 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_ids array optional Return only items with these IDs (boards and docs)
select_kinds array optional 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.).
spatial boolean optional Include spatial annotations (boards only, requires detail: detailed). Default: false.
viewport object optional Bounding box in board coordinates to crop the image to (image mode only).
whimsicalmcp_file_tree # Browse the workspace file hierarchy to list folders, boards, and docs with optional depth and type filtering. 4 params

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

Name Type Required Description
depth integer optional How many levels deep to show (default 2, max 5)
filter string optional 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.
folder_id string optional Folder, section, or team id (base58 or UUID) to browse — returns the file tree below it. Team ids come from filter="teams" or list_workspaces. Omit to see the whole workspace tree.
workspace_id string optional Target workspace ID. Defaults to most recently active workspace. Use list_workspaces to see options.
whimsicalmcp_generate_diagram # Generate a Whimsical flowchart, mind map, or sequence diagram from structured data or Mermaid syntax. 6 params

Generate a Whimsical flowchart, mind map, or sequence diagram from structured data or Mermaid syntax.

Name Type Required Description
type string required Diagram type to generate
board_id string optional Add to existing board. Omit to create a new board.
data string optional Content data — format varies by type. Use how_to(type) for syntax.
parent_id string optional Folder or team section ID to create in. Defaults to Private section.
title string optional Title for the board
workspace_id string optional Workspace ID (UUID). Use list_workspaces to see options. Defaults to most recently active workspace.
whimsicalmcp_generate_mind_map # Generate a Whimsical mind map from indented markdown, where the first line is the root and children are bulleted. 5 params

Generate a Whimsical mind map from indented markdown, where the first line is the root and children are bulleted.

Name Type Required Description
board_id string optional Add to existing board. Omit to create a new board.
data string optional Mind map content as {"markdown": "Root Topic\n- Child 1\n - Grandchild\n- Child 2"}. First line is root, children use '- ' bullets, indent 2 spaces per level.
parent_id string optional Folder or team section ID to create in. Defaults to Private section.
title string optional Title for the board
workspace_id string optional Workspace ID (UUID). Use list_workspaces to see options. Defaults to most recently active workspace.
whimsicalmcp_generate_wireframe # Generate a Whimsical wireframe with flexbox layout using containers, buttons, inputs, and other UI elements. 5 params

Generate a Whimsical wireframe with flexbox layout using containers, buttons, inputs, and other UI elements.

Name Type Required Description
board_id string optional Add to existing board. Omit to create a new board.
data string optional Content data — format varies by type. Use how_to(type) for syntax.
parent_id string optional Folder or team section ID to create in. Defaults to Private section.
title string optional Title for the board
workspace_id string optional Workspace ID (UUID). Use list_workspaces to see options. Defaults to most recently active workspace.
whimsicalmcp_get_board_items # Fetch board objects by file ID for rendering in the Whimsical widget. 4 params

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

Name Type Required Description
fileId string required Board file ID (base58 or UUID)
fields array optional Object fields to include (omit for all). Lightweight: rect, objectType, text, fillColor, parentId, url. Heavy: gfx, rgfx, overlayGfx, hitboxes, shadowPathD.
limit integer optional Max objects per page (omit for all)
offset integer optional Object offset for pagination (default 0)
whimsicalmcp_how_to # Look up Whimsical-specific syntax, examples, and guides for creating diagrams and wireframes. 2 params

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

Name Type Required Description
domain string optional 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.
topic string optional Topic keyword (e.g. 'flowchart', 'table', 'colors') or search query
whimsicalmcp_list_workspaces # List all workspaces the authenticated user belongs to, including team IDs and member roles. 0 params

List all workspaces the authenticated user belongs to, including team IDs and member roles.

whimsicalmcp_wireframe_edit # Reflow or edit Whimsical wireframe elements using operations or a flexbox layout tree. 6 params

Reflow or edit Whimsical wireframe elements using operations or a flexbox layout tree.

Name Type Required Description
board_id string required Board file ID
target_id string required Wireframe frame ID to edit (from board_read or create)
frame_type string optional Override frame type if auto-detection fails. Valid: plain, desktop, iphone-14, iphone-x, iphone-8, ipad, android, android-tablet, apple-watch
layout array optional Layout mode: JSON layout tree for structural changes with flexbox reflow. Cannot be used with operations.
operations array optional Operations mode: direct property edits and deletes. Cannot be used with layout.
title string optional Frame title (preserves existing if omitted)