Eraser Diagram Renderer

A Python MCP (Model Context Protocol) server and CLI tool to render diagrams using the Eraser API.

Features

• 📊 Multiple Diagram Types: Sequence, flowchart, ER, cloud architecture, and more

• 🎨 Customizable: Themes, backgrounds, and scaling options

• 📦 Flexible Output: Get image URLs or base64-encoded file content

• 🔗 Eraser File URL: Returns link to edit diagram in Eraser

• ✅ Icon Validation: Checks for undefined icons and provides warnings

Documentation

• MCP Usage Guide - How to use with Claude Desktop, VS Code, Windsurf, or other environments.

• Eraser Docs - General Eraser documentation

• Eraser Diagram-as-code Documentation - Information about the syntax

• Eraser DSL API Reference - Information about the endpoints and parameters used

Basic Usage

This will output JSON with the image URL:

If undefined icons are detected:

Parameters

• --diagram-type (required): Type of diagram (e.g., sequence-diagram, cloud-architecture-diagram)

• --code (required): Diagram code in Eraser syntax

• --return-file: Return base64-encoded image data instead of URL (defaults to False)

• --no-background: Disable background (defaults to background enabled)

• --theme: Choose "light" or "dark" theme (defaults to "light")

• --scale: Scale factor - "1", "2", or "3" (defaults to "1")

Note: Due to a bug in the Eraser API, the image cache is only invalidated when the diagram code changes. Changes to theme or background parameters alone will not generate a new image if the same code was previously rendered with different settings.

Authentication

For CLI usage, set your Eraser API token in one of these ways:

1. Environment variable:

   export ERASER_API_TOKEN=your_token_here python render_eraser_diagram.py --diagram-type sequence-diagram --code "A -> B"

2. .env in the project directory:

   echo "ERASER_API_TOKEN=your_token_here" > .env

For MCP server usage with Claude Desktop, see the MCP Usage Guide.

Icon Validation

This tool validates icon references against the standard Eraser icons list (provided in eraser-standard-icons.csv). If you use custom icons that aren't in the standard list:

• You'll receive a warning in the response

• The diagram will still be generated

• To disable icon validation, set SKIP_ICON_CHECK=true:

  SKIP_ICON_CHECK=true python render_eraser_diagram.py --diagram-type flowchart --code "custom-icon: My Service"

Handling Special Characters

For multi-line diagrams and special characters:

• Use \n for line breaks

• Use \" for quotes within the code

• Use \\ for literal backslashes

Examples

Multi-line sequence diagram (returns URL):

Output:

With JSON data and return file:

Output:

Cloud architecture with light theme:

Debug mode to see processed code:

Supported Diagram Types

• sequence-diagram

• cloud-architecture-diagram

• flowchart-diagram

• entity-relationship-diagram

• And more (check Eraser Diagram-as-code documentation)

Requirements

• Python 3.10 or higher

• Eraser API token

Installation

Using pip:

Using uv (fast Python package manager):

HTTP Transport (Streamable HTTP)

The server supports both stdio (default) and Streamable HTTP transport for remote access.

Running with HTTP Transport

Environment Variables

Bearer Token Authentication

To enable authentication for the HTTP endpoint, set MCP_AUTH_TOKEN:

Clients must include the token in the Authorization header:

Docker Deployment

Using Docker Compose (Recommended)

1. Copy .env.example to .env and configure:

   cp .env.example .env # Edit .env with your ERASER_API_TOKEN

2. Start the server:

   docker-compose up -d

3. The server will be available at http://localhost:8000/mcp

Using Docker Directly

Client Configuration for HTTP

Configure your MCP client to connect via Streamable HTTP:

Troubleshooting

• If you get an API error, check that your token in .env is valid

• Use DEBUG=1 to see how your code is being processed

• Ensure proper escaping of special characters in your shell

• If you see icon warnings, check if your icons are custom or set SKIP_ICON_CHECK=true

• For HTTP transport issues, check that the port is not in use and firewall allows connections