eraser-io-mcp-server
# 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