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

python render_eraser_diagram.py --diagram-type sequence-diagram --code "Alice -> Bob: Hello"

This will output JSON with the image URL:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_url": "https://app.eraser.io/workspace/...",
  "create_eraser_file_url": "https://app.eraser.io/workspace/..."
}

If undefined icons are detected:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_url": "https://app.eraser.io/workspace/...",
  "create_eraser_file_url": "https://app.eraser.io/workspace/...",
  "warning": "Warning: The following icons are not defined in the standard Eraser icons list: custom-icon. These icons may not render correctly. You can disable this warning by setting SKIP_ICON_CHECK=true."
}

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 file 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):

python render_eraser_diagram.py --diagram-type sequence-diagram \
  --code "Alice -> Bob: Hello\nBob -> Alice: Hi there\nAlice -> Bob: How are you?"

Output:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_url": "https://app.eraser.io/workspace/...",
  "create_eraser_file_url": "https://app.eraser.io/workspace/..."
}

With JSON data and return file:

python render_eraser_diagram.py --diagram-type sequence-diagram \
  --code "User -> API: POST /data {\"key\": \"value\"}\nAPI -> User: 200 OK" \
  --return-file

Output:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_blob": "iVBORw0KGgoAAAANSUhEUgA..."
}

Cloud architecture with light theme:

python render_eraser_diagram.py --diagram-type cloud-architecture-diagram \
  --code "AWS S3 Bucket\n|\nAWS Lambda" --theme light

Debug mode to see processed code:

DEBUG=1 python render_eraser_diagram.py --diagram-type sequence-diagram \
  --code "A -> B: Test\nB -> C: Response"

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:

pip install -e .

Using uv (fast Python package manager):

uv pip install -e .

HTTP Transport (Streamable HTTP)

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

Running with HTTP Transport

# Local HTTP server
python main.py --transport http --port 8000

# Server will be available at http://localhost:8000/mcp

Environment Variables

Variable	Default	Description
ERASER_API_TOKEN	(required)	Your Eraser.io API token
MCP_TRANSPORT	stdio	Transport protocol: stdio or http
MCP_HOST	0.0.0.0	Host to bind for HTTP transport
MCP_PORT	8000	Port to bind for HTTP transport
MCP_AUTH_TOKEN	(empty)	Bearer token for HTTP authentication (optional)

Bearer Token Authentication

To enable authentication for the HTTP endpoint, set MCP_AUTH_TOKEN:

export MCP_AUTH_TOKEN=your_secret_token
python main.py --transport http

Clients must include the token in the Authorization header:

Authorization: Bearer your_secret_token

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

# Build
docker build -t eraser-mcp .

# Run
docker run -p 8000:8000 \
  -e ERASER_API_TOKEN=your_token \
  -e MCP_AUTH_TOKEN=optional_auth_token \
  eraser-mcp

Client Configuration for HTTP

Configure your MCP client to connect via Streamable HTTP:

{
  "mcpServers": {
    "eraser": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your_auth_token"
      }
    }
  }
}

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