# Eraser Diagram Renderer
A Python MCP (Model Context Protocol) server and CLI tool to render diagrams using the [Eraser](https://www.eraser.io/) 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](MCP_USAGE.md) - How to use with Claude Desktop, VS Code, Windsurf, or other environments.
- [Eraser Docs](https://docs.eraser.io/docs/what-is-eraser) - General Eraser documentation
- [Eraser Diagram-as-code Documentation](https://docs.eraser.io/docs/diagram-as-code) - Information about the syntax
- [Eraser DSL API Reference](https://docs.eraser.io/reference/generate-diagram-from-eraser-dsl) - Information about the endpoints and parameters used
## Basic Usage
```bash
python render_eraser_diagram.py --diagram-type sequence-diagram --code "Alice -> Bob: Hello"
```
This will output JSON with the image URL:
```json
{
"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:
```json
{
"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**:
```bash
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:
```bash
echo "ERASER_API_TOKEN=your_token_here" > .env
```
For MCP server usage with Claude Desktop, see the [MCP Usage Guide](MCP_USAGE.md).
## 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`:
```bash
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):
```bash
python render_eraser_diagram.py --diagram-type sequence-diagram \
--code "Alice -> Bob: Hello\nBob -> Alice: Hi there\nAlice -> Bob: How are you?"
```
Output:
```json
{
"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:
```bash
python render_eraser_diagram.py --diagram-type sequence-diagram \
--code "User -> API: POST /data {\"key\": \"value\"}\nAPI -> User: 200 OK" \
--return-file
```
Output:
```json
{
"success": true,
"message": "Diagram rendered successfully",
"image_blob": "iVBORw0KGgoAAAANSUhEUgA..."
}
```
### Cloud architecture with light theme:
```bash
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:
```bash
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](https://docs.eraser.io/docs/diagram-as-code))
## Requirements
- Python 3.10 or higher
- Eraser API token
## Installation
Using pip:
```bash
pip install -e .
```
Using uv (fast Python package manager):
```bash
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
```bash
# 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`:
```bash
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:
```bash
cp .env.example .env
# Edit .env with your ERASER_API_TOKEN
```
2. Start the server:
```bash
docker-compose up -d
```
3. The server will be available at `http://localhost:8000/mcp`
### Using Docker Directly
```bash
# 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:
```json
{
"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
