Whimsical’s desktop MCP (Model Context Protocol) server is built into the Whimsical desktop app and runs locally on your machine, so AI coding agents like Claude, Cursor, and Codex can read and write directly to your Whimsical workspace.

This doc should get you started using Whimsical with your AI agent - use the list on the right to jump to specific setup instructions.

If you run into any trouble or have questions, just reach out to our support team.

Step 1: Open the Whimsical desktop appCopied!Link to this section

Whimsical’s desktop MCP server is built into our desktop app, available for macOS and Windows. You can download it from here.

The desktop app must be running for the MCP server to work.

Step 2: Setup your MCP clientCopied!Link to this section

The desktop MCP server is designed to be used locally with coding agents. Follow the instructions below for your specific client to add the MCP server.

Claude CodeCopied!Link to this section

Run the following command in your terminal:

CodexCopied!Link to this section

Run the following command in your terminal:

CursorCopied!Link to this section

1. Open Cursor → Settings → Cursor Settings.
2. Go to Tools & MCP.
3. Click Add custom MCP or + New MCP server.
4. Enter the following configuration and save:

Claude DesktopCopied!Link to this section

Download the MCP installer for Claude Desktop here, and double click the downloaded file to install.

Just make sure the Whimsical desktop app is installed and running beforehand. 👌

Copilot in VS CodeCopied!Link to this section

Make sure you have access to Copilot in VS Code. Once you have access, you can connect to Whimsical’s MCP server by creating an mcp.json file in the .vscode folder of your project and adding the following:

AntigravityCopied!Link to this section

1. Open the MCP store via the “…” dropdown at the top of the agent panel.
2. Click Manage MCP Servers.
3. Click View raw config.
4. Add the following configuration to mcp_config.json

OpenCodeCopied!Link to this section

Add the following to your opencode.json file:

Note: You might need to restart OpenCode before the MCP server will connect.

Other clientsCopied!Link to this section

While we haven't tested other MCP clients, they might work with a similar config.

For clients that don't directly support local HTTP transport, you might be able to use mcp-remote option.

For example, for Claude Desktop you can also add the following config to ~/Library/Application Support/Claude/claude_desktop_config.json:

Step 3: Verify the connectionCopied!Link to this section

• Make sure the desktop app is open - The MCP server only runs while the Whimsical desktop app is active. If the desktop app is not be running before you start your coding agent, your AI client will fail to connect.
• Ask your AI client “What Whimsical tools do you have available?” If the MCP is connected, you’ll get a list of tools such as create_diagram, search_files etc.
• You can always check directly:
  • Type /mcp in Claude code, Codex or OpenCode to see a list of connected MCP servers.
  • Check the MCP settings page in Claude desktop, Cursor, or Antigravity.
  • Run MCP: List Servers from the Command Palette in VS Code.

Step 3: Prompt your MCP clientCopied!Link to this section

Start a new client session and ask it to do things in Whimsical. To get started, you can ask it “What can you do with Whimsical MCP?”. 👌

So, what can it do?Copied!Link to this section

Create diagrams from your codebaseCopied!Link to this section

Ask your AI to turn code into visual diagrams in Whimsical. Try prompts like “Create a flowchart of the authentication flow in this codebase”, “Map the relationships between these microservices”, or “Generate a sequence diagram showing how this API request is processed”.

Search and reference your Whimsical filesCopied!Link to this section

Your AI can search and read Whimsical files so you can reference them in context. Try “Find the system architecture diagram I made last month” or “Summarize the user flow we mapped out in Whimsical”.

Plan and brainstorm visuallyCopied!Link to this section

Use your AI to create mind maps, wireframe outlines, and planning documents directly in Whimsical. Try “Create a mind map of the key features for this project” or “Make a wireframe outline for a new settings page”.

TroubleshootingCopied!Link to this section

Tools aren’t showing up in my AI clientCopied!Link to this section

Make sure the Whimsical desktop app is open before you launch Claude, or whichever client you’re using, as the MCP server only runs while the app is active. Then start a new session in your AI client (most clients only scan for MCP tools at session start).

If you’re using Claude Desktop or Cursor, double-check your config file for typos in the URL. It should be exactly http://localhost:21190/mcp .

I’m connected but getting errorsCopied!Link to this section

Check that you’re signed into your Whimsical account in the desktop app, as the MCP needs an active session to access your workspace. If you’re signed in but still seeing errors, try signing out and back in, then restart the desktop app.

The connection stopped workingCopied!Link to this section

Try quitting and relaunching the Whimsical desktop app, then start a fresh session in your AI client.

I can’t find my Whimsical contentCopied!Link to this section

The MCP can only access content in the workspace you’re currently signed into in the Whimsical desktop app. If you belong to multiple workspaces, make sure you’re signed into the right one. Check out this article if you’re unsure how to switch workspaces.

If you’re still having trouble, or have questions, just reach out to our support team.