MCP Server Reference

Complete reference for the diagrams.love MCP server. Connect any MCP-compatible AI tool and manage diagrams programmatically.

What is MCP?

MCP (Model Context Protocol) is an open protocol that lets AI tools — like Claude Desktop, Claude Code, Cursor, and Windsurf — connect to external services and use their capabilities as native tools. The diagrams.love MCP server exposes your diagram workspace as a set of commands that AI can call directly.

With the diagrams.love MCP server, your AI can: create and update diagrams from scratch, read existing diagrams and their content, organize diagrams into projects, manage tags and statuses, browse version history, and export diagrams as images — all without leaving the conversation.

Requirements

• Node.js 18 or newer — check with node --version
• Pro or Max plan — MCP access is not available on the Free plan
• API token — generated in your Profile under MCP Integration
• MCP-compatible client — Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP host

Quick Start

1. 1

   Get your API token

   Open Profile & Settings and scroll to the MCP Integration section. Click "Generate token" and copy it. Tokens start with schog_.

2. 2

   Add config to your MCP client

   See the client configs below. Replace your_token_here with your actual token.

3. 3

   Restart your MCP client

   Fully restart the application (not just reload). The diagrams-love server appears in the tools list. Verify by asking the AI: "List my diagrams".

Client Configurations

The npm package diagrams-love-mcp works with any MCP host. Choose your client below.

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "diagrams-love": {
      "command": "npx",
      "args": ["-y", "diagrams-love-mcp"],
      "env": {
        "DIAGRAMS_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Desktop

Edit the config file: on macOS it is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "diagrams-love": {
      "command": "npx",
      "args": ["-y", "diagrams-love-mcp"],
      "env": {
        "DIAGRAMS_TOKEN": "your_token_here"
      }
    }
  }
}

Cursor

Go to Cursor Settings → MCP → Add server. Or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "diagrams-love": {
      "command": "npx",
      "args": ["-y", "diagrams-love-mcp"],
      "env": {
        "DIAGRAMS_TOKEN": "your_token_here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "diagrams-love": {
      "command": "npx",
      "args": ["-y", "diagrams-love-mcp"],
      "env": {
        "DIAGRAMS_TOKEN": "your_token_here"
      }
    }
  }
}

Diagram Management

Commands for listing, reading, creating, and managing your diagrams (called "schemas" in the API).

Project Management

Projects are folders for organizing diagrams. Use them to group related diagrams by topic, team, or product area.

Tags

Tags categorize elements within a diagram. Each diagram has its own tag dictionary. Tags are referenced by their ID, not their name.

Statuses

Statuses track the state of individual cards (e.g. New, In Progress, Done). Each diagram has its own status dictionary.

Version History

Every save to a diagram creates a version snapshot. Use these commands to browse history and restore previous states.

Batch Operations

Apply changes to multiple elements in a single API call. Much more efficient than calling individual element updates one by one.

// Change color of 3 elements to green
batch_update_elements(
  schema_id="abc123",
  element_ids=["el1", "el2", "el3"],
  updates={"color": "light_green"}
)

// Add a tag to multiple elements
batch_update_elements(
  schema_id="abc123",
  element_ids=["el4", "el5"],
  updates={"add_tags": ["tag-id-xyz"]}
)

Visual Export

Generate visual representations of diagrams as image files. Useful for embedding diagrams in documents, reports, or presentations.

Password Protection

Diagrams can be protected with a password. When a password is set, all MCP tool calls that access the diagram must include the password parameter. Password protection only affects MCP access — the web UI and public shared links are not affected.

Example: accessing a password-protected diagram

// Without password — returns error if schema is protected
get_schema(schema_id="abc123")

// With password — works correctly
get_schema(schema_id="abc123", password="mypassword")

// Same for all other tools that accept a schema_id
update_schema(schema_id="abc123", password="mypassword", elements=[...])

Element Structure

Every diagram is plain JSON. Each element in the elements array has the following structure:

{
  "id": "unique-element-id",       // required: unique string ID
  "type": "card",                  // required: card | condition | ascii | html | iframe
  "title": "Card Title",           // card title text
  "description": "Detail text",    // optional: description shown below title
  "color": "light_blue",           // background fill color (see Colors section)
  "borderColor": "blue",           // optional: border color (see Colors section)
  "tags": ["tag-id-1"],            // optional: array of tag IDs (not names!)
  "completed": false,              // optional: mark card as completed
  "eventDate": "2025-12-31",       // optional: ISO 8601 date for deadline/event
  "content": "...",                // REQUIRED for ascii/html/iframe types
  "viewportType": "desktop",       // optional: for iframe — desktop|tablet|mobile
  "connections": [                 // optional: outgoing connections
    {
      "to": "target-element-id",   // required: target element ID
      "label": "optional label",   // optional: text on the connection arrow
      "style": "dashed"            // optional: arrow style
    }
  ]
  // DO NOT specify x, y, width, height — layout is automatic!
}

Element Types

Colors

Always use named color values — never HEX. The color field sets the background fill. The optional borderColor field sets the border accent.

Connections

Connections are defined inline inside each element's connections array. Each connection points to the target element's ID.

{
  "id": "step-1",
  "type": "card",
  "title": "Step 1",
  "connections": [
    { "to": "step-2" },                           // simple connection
    { "to": "error-path", "label": "on error" },  // with label
    { "to": "step-3", "label": "OK", "style": "dashed" } // dashed line
  ]
}

Full Example

A complete diagram showing a user registration flow with tags, colors, conditions, and connections:

{
  "name": "User Registration",
  "description": "New user signup flow",
  "elements": [
    {
      "id": "start",
      "type": "card",
      "title": "Registration Form",
      "color": "light_green",
      "tags": ["user"],
      "connections": [{"to": "validate"}]
    },
    {
      "id": "validate",
      "type": "condition",
      "title": "Validation",
      "color": "light_yellow",
      "tags": ["system"],
      "connections": [
        {"to": "save", "label": "valid"},
        {"to": "error", "label": "invalid"}
      ]
    },
    {
      "id": "save",
      "type": "card",
      "title": "Save to DB",
      "color": "light_blue",
      "tags": ["system"],
      "connections": [{"to": "success"}]
    },
    {
      "id": "error",
      "type": "card",
      "title": "Show Error",
      "color": "light_red",
      "tags": ["user"]
    },
    {
      "id": "success",
      "type": "card",
      "title": "Welcome Email",
      "color": "light_green",
      "tags": ["system"]
    }
  ],
  "tagsDictionary": [
    {"id": "user", "name": "user", "color": "#4CAF50"},
    {"id": "system", "name": "system", "color": "#2196F3"}
  ]
}

Best Practices

Let auto-layout do the work

Never specify x, y, width, or height for new elements. The layout engine positions cards automatically. If you copy coordinates from existing elements, cards will overlap. After creating a diagram, call relayout_schema if the layout looks off.

Use meaningful element IDs

Choose descriptive IDs like step-login, check-auth, db-save instead of el1, el2. IDs are used in connections — descriptive names make the JSON self-documenting and easier to update later.

Typical create-then-edit workflow

1. Call create_schema with the full element list and connections
2. Call get_schema to read back what was created (with server-assigned IDs if any)
3. Use batch_update_elements to adjust colors or tags in bulk
4. Call relayout_schema if the layout needs a refresh
5. Use export_schema_to_json with file_path to save a backup

Managing large diagrams

For diagrams with 20+ elements, always use file_path with export_schema_to_json and import_schema_from_json. This avoids filling the AI context window with JSON. The file is read and written directly by the MCP server.

Asking AI to create diagrams

The most effective prompt pattern is: describe the structure you want, specify the element types and relationships, mention any color coding or tagging scheme. Example: "Create a deployment pipeline diagram: local dev → CI build → staging → production approval → production deploy. Color stages as teal, approvals as yellow. Tag CI/CD steps with a 'automation' tag."

Troubleshooting

Token issues

• Tokens start with schog_ — if yours does not, generate a new one in Profile
• Make sure you copied the complete token without trailing spaces or line breaks
• Tokens do not expire automatically — they only become invalid if you revoke them
• MCP access requires Pro or Max plan — verify your subscription in Profile

Connection not working

• Validate your JSON config — a single trailing comma breaks JSON parsing silently
• The environment variable must be named exactly DIAGRAMS_TOKEN (legacy: SCHEMEOG_TOKEN is also accepted)
• Check Node.js version: node --version — must be 18 or newer
• Fully restart your MCP client after any config change — reload is not enough
• Try running npx diagrams-love-mcp directly in a terminal to see error output

Cards overlapping after create

• Do not set x or y on new elements — remove those fields entirely
• Call relayout_schema on the diagram to reset all positions

Element downgraded to card

• The ascii, html, and iframe types require a content field — without it, the element becomes a regular card automatically
• There is no asciiContent or htmlContent field — the unified field name is always content