Whimsical MCP Server

What is Whimsical MCP Server about?

Creates Whimsical diagrams programmatically by accepting Mermaid markup produced by an MCP client (e.g., Claude). The server calls Whimsical's API, uploads the diagram, and returns a shareable URL together with a base64 image.

How to use Whimsical MCP Server?

1. Installation
   • Via Smithery (recommended):

     npx -y @smithery/cli install BrockReece/whimsical-mcp-server --client claude
     

   • Manual:

     git clone https://github.com/BrockReece/whimsical-mcp-server.git
     cd whimsical-mcp-server
     yarn install
     yarn build
     

2. Configure the MCP client to point to the built dist/index.js file, e.g.:

   {
     "mcpServers": {
       "whimsical": {
         "command": "node",
         "args": ["/path/to/whimsical-mcp-server/dist/index.js"]
       }
     }
   }
   

3. Run the client; the server will accept Mermaid markup, create the diagram, and respond with the URL and base64 image.

Key features of Whimsical MCP Server

• Accepts Mermaid markup generated by any MCP‑compatible client.
• Automatically creates and publishes Whimsical diagrams via Whimsical’s API.
• Returns both a public diagram URL and a base64‑encoded PNG for immediate visual feedback.
• Simple integration: configure the MCP client with a Node command.

Use cases of Whimsical MCP Server

• Automated architecture diagram generation from AI‑generated descriptions.
• Iterative design loops where an agent refines Mermaid markup based on image feedback.
• Documentation pipelines that embed up‑to‑date diagrams directly from source code comments or design specs.
• Chat‑assistant extensions enabling users to request visualizations without manual drawing.

FAQ from the Whimsical MCP Server

Q: Do I need a Whimsical account or API key? A: Yes, the server uses Whimsical’s public API, so an authenticated account is required. Set the appropriate credentials in your environment before running the server.

Q: Which markup languages are supported? A: Currently only Mermaid syntax is accepted.

Q: Can I customize the diagram’s style? A: Styling can be controlled within the Mermaid markup (themes, colors, etc.) before it is sent to the server.

Q: What runtime is needed? A: Node.js (LTS) with Yarn for building; the built server runs on any standard Node environment.

Q: How do I handle rate limits? A: Respect Whimsical’s API usage limits; consider adding back‑off logic in the MCP client if you anticipate high request volumes.

Whimsical MCP Server

Whimsical now has an official MCP server available here

A third-party Model Context Protocol (MCP) server that enables the creation of Whimsical diagrams agentically. This server integrates with Whimsical's API to generate diagrams from Mermaid markup.

Demo

Here's an example of a complex system architecture diagram created using this MCP server and Claude - it shows the Model Context Protocol (MCP) architecture itself:

Features

• Create Whimsical diagrams using Mermaid markup generated by the MCP Client (Claude, Windsurf, etc.)
• Returns both the Whimsical diagram URL and a base64 encoded image to allow the Client to iterate on it's original markup

Installation

Installing via Smithery

To install Whimsical MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install BrockReece/whimsical-mcp-server --client claude

Manual Installation

# Clone the repository
git clone https://github.com/BrockReece/whimsical-mcp-server.git

# Install dependencies
yarn install

# Build the project
yarn build

Integration with MCP Client

Update the MCP Client's config to point to this repository's dist folder eg:

    {
        "mcpServers": {
            "whimsical": {
                "command": "node",
                "args": [
                    "/path/to/this/repo/whimsical-mcp-server/dist/index.js"
                ]
            }
        }
    }

License

This project is licensed under the MIT License.