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
8 · 5 · 58 read5 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
    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).
    detailstring
    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, 📝]`.one of simpledetailed
    expand_groupsboolean
    Show all objects flat instead of collapsing groups into summaries (boards only).
    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.
    limitinteger
    Max objects/blocks to return (default: 50 for boards, 200 for docs, max: 200)
    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.).
    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" or list_workspaces. Omit to see the whole workspace tree.
    workspace_idstring
    Target workspace ID. Defaults to most recently active workspace. Use list_workspaces to see options.
  • 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_list_workspacesList all workspaces the authenticated user belongs to, including team IDs and member roles.Read-only

    List Workspaces

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

    Inputs

    This tool takes no inputs.

All 18 in Design