Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Whimsical MCP connector

OAuth 2.1/DCRDesignProductivityAI

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.

NameTypeRequiredDescription
board_idstringrequiredBoard file ID
orientationstringoptionalLayout direction (td=top-to-bottom, lr=left-to-right, bt=bottom-to-top, rl=right-to-left). Inferred from connector flow when omitted.
parent_idstringoptionalOptional: scope layout to descendants of this object id (e.g. a group/container). Omit to lay out all root-level shapes on the file.
spacingstringoptionalSpacing 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.

NameTypeRequiredDescription
actionstringrequiredWhich comment operation to perform.
cell_idstringoptionalFor 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_idstringoptionalFor edit/delete: id of the specific comment to modify.
contentstringoptionalFor create/reply/edit: markdown content for the comment.
item_idstringoptionalFor create: id of the board, doc, board object, or table row to attach the thread to.
thread_idstringoptionalFor 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.

NameTypeRequiredDescription
item_idstringrequiredBoard, doc, board-object, doc-block, or table-row id (short-id, base58, or UUID).
cell_idstringoptionalOptional 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.
limitintegeroptionalMaximum 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.

NameTypeRequiredDescription
typestringrequiredWhat 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_idstringoptionalAdd to existing board. Omit to create new board. Required for wireframe.
datastringoptionalContent 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_idstringoptionalFolder 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.
placementobjectoptionalPosition 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.
titlestringoptionalTitle or name for the created item
workspace_idstringoptionalWorkspace ID (UUID). Use list_workspaces to see options. Defaults to most recently active workspace.
xnumberoptionalX position on board. Mutually exclusive with placement.
ynumberoptionalY 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.

NameTypeRequiredDescription
idstringrequiredId 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.

NameTypeRequiredDescription
datastringoptionalDocument content as a markdown string.
parent_idstringoptionalFolder or team section ID to create in. Defaults to Private section.
titlestringoptionalDocument title
workspace_idstringoptionalWorkspace 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.

NameTypeRequiredDescription
idstringrequiredBoard or doc ID (from create, fetch, or a previous tool response)
operationsarrayrequiredArray 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.

NameTypeRequiredDescription
idstringrequiredFile or object ID (6-char short-id, UUID, or base58) from search results or a previous tool call
board_idstringoptionalParent board ID — required when fetching a table object. The table_id goes in 'id'.
crop_idsarrayoptionalSpecific object IDs to crop the image to (image mode only).
detailstringoptionalDetail 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_groupsbooleanoptionalShow all objects flat instead of collapsing groups into summaries (boards only).
grep_textarrayoptionalFilter to items whose text contains any of these terms (boards and docs, case-insensitive).
imagebooleanoptionalReturn a rendered PNG image instead of text (boards only). Use scope, crop_ids, or viewport to crop.
limitintegeroptionalMax objects/blocks to return (default: 50 for boards, 200 for docs, max: 200)
scopestringoptionalIMPORTANT 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_idsarrayoptionalReturn only items with these IDs (boards and docs)
select_kindsarrayoptionalFilter 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.).
spatialbooleanoptionalInclude spatial annotations (boards only, requires detail: detailed). Default: false.
viewportobjectoptionalBounding 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.

NameTypeRequiredDescription
depthintegeroptionalHow many levels deep to show (default 2, max 5)
filterstringoptionalSet 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_idstringoptionalFolder, 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_idstringoptionalTarget 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.

NameTypeRequiredDescription
typestringrequiredDiagram type to generate
board_idstringoptionalAdd to existing board. Omit to create a new board.
datastringoptionalContent data — format varies by type. Use how_to(type) for syntax.
parent_idstringoptionalFolder or team section ID to create in. Defaults to Private section.
titlestringoptionalTitle for the board
workspace_idstringoptionalWorkspace 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.

NameTypeRequiredDescription
board_idstringoptionalAdd to existing board. Omit to create a new board.
datastringoptionalMind 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_idstringoptionalFolder or team section ID to create in. Defaults to Private section.
titlestringoptionalTitle for the board
workspace_idstringoptionalWorkspace 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.

NameTypeRequiredDescription
board_idstringoptionalAdd to existing board. Omit to create a new board.
datastringoptionalContent data — format varies by type. Use how_to(type) for syntax.
parent_idstringoptionalFolder or team section ID to create in. Defaults to Private section.
titlestringoptionalTitle for the board
workspace_idstringoptionalWorkspace 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.

NameTypeRequiredDescription
fileIdstringrequiredBoard file ID (base58 or UUID)
fieldsarrayoptionalObject fields to include (omit for all). Lightweight: rect, objectType, text, fillColor, parentId, url. Heavy: gfx, rgfx, overlayGfx, hitboxes, shadowPathD.
limitintegeroptionalMax objects per page (omit for all)
offsetintegeroptionalObject 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.

NameTypeRequiredDescription
domainstringoptionalStructured 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.
topicstringoptionalTopic 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.

NameTypeRequiredDescription
board_idstringrequiredBoard file ID
target_idstringrequiredWireframe frame ID to edit (from board_read or create)
frame_typestringoptionalOverride frame type if auto-detection fails. Valid: plain, desktop, iphone-14, iphone-x, iphone-8, ipad, android, android-tablet, apple-watch
layoutarrayoptionalLayout mode: JSON layout tree for structural changes with flexbox reflow. Cannot be used with operations.
operationsarrayoptionalOperations mode: direct property edits and deletes. Cannot be used with layout.
titlestringoptionalFrame title (preserves existing if omitted)