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:

Environment variable:

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

.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)

Copy .env.example to .env and configure:

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

Start the server:
```
docker-compose up -d
```
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

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")

Authentication

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

Environment variable:

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

.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)

Copy .env.example to .env and configure:

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

Start the server:
```
docker-compose up -d
```
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