whimsical

Whimsical MCP Server enables programmatic creation of Whimsical diagrams from Mermaid markup. It integrates with the MCP ecosystem so clients can request diagram generation and receive both a public diagram URL and a base64-encoded image for immediate rendering or iterative editing. The server acts as a bridge between Mermaid-based diagrams and Whimsical's API, producing diagrams that reflect the requested structure and relationships as defined in Mermaid.

To use it, install and run the MCP server and configure your MCP client to point at the server's dist/index.js entry (as shown in the integration example). The client sends a request containing the Mermaid markup along with any needed parameters (such as diagram type or workspace context, if supported). The server then forwards the request to Whimsical, awaits the response, and returns both the diagram URL and a base64 image back to the client for immediate display or further iteration.

Prerequisites:

• Node.js and yarn/npm installed
• Access to the repository (clone or install via Smithery)

Manual installation steps:

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

# Install dependencies
cd whimsical-mcp-server
yarn install

# Build the project
yarn build

Smithery installation (optional but recommended for automatic deployment):

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

Integration with MCP Client (example):

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

If you prefer a different setup, ensure your server entry point is reachable and that the built distribution (dist) contains index.js as the MCP entry.

Tips and considerations:

• Ensure the dist/index.js exists after building; the MCP client will invoke this entry point directly.
• If you plan to publish or run multiple instances, consider environment-specific configurations (API keys, workspace IDs) and secure storage for any tokens required by Whimsical.
• Check for rate limits on Whimsical API usage and implement retry/backoff in the client if needed.
• When using Smithery for automatic deployment, verify that the deployed server's path aligns with the MCP client's configured path to dist/index.js.
• Maintain version alignment between Mermaid markup capabilities and Whimsical API features to avoid unsupported syntax.
• Keep the MCP server updated with Whimsical API changes; monitor the repository for upstream updates.