iflow-mcp_buck-0x-eraser-io-mcp-server 1.0.0
MCP server for rendering diagrams using Eraser API
Requires Python: >=3.10

# 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