mcp-server-diagramai

An MCP server implementation for DiagramAI integration, enabling AI agents to create, read, edit, and delete diagrams in real-time.

Features

Resources

• Expose diagram list and project structure
• Real-time diagram state access
• Project-based organization

Tools

• create_diagram: Create new diagrams with specified content
• get_diagram: Retrieve diagram by ID
• update_diagram: Modify existing diagrams
• delete_diagram: Remove diagrams
• add_node: Add nodes to diagrams
• add_edge: Add connections between nodes
• list_diagrams: Get all accessible diagrams
• get_diagram_status: Check diagram state and metadata

Installation

From npm (Recommended)

npm install -g mcp-server-diagramai

From source

git clone https://github.com/PadsterH2012/mcp-server-diagramai.git
cd mcp-server-diagramai
npm install
npm run build

Usage with Claude Desktop

Configuration File

Paths to Claude Desktop config file:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Published Package Configuration

{
  "mcpServers": {
    "diagramai": {
      "command": "npx",
      "args": [
        "mcp-server-diagramai",
        "--api-url", "${DIAGRAMAI_API_URL}",
        "--api-key", "${DIAGRAMAI_API_KEY}"
      ]
    }
  }
}

Development Configuration

{
  "mcpServers": {
    "diagramai": {
      "command": "/PATH/TO/node",
      "args": [
        "/PATH/TO/mcp-server-diagramai/dist/index.js"
      ],
      "env": {
        "DIAGRAMAI_API_URL": "http://localhost:3000",
        "DIAGRAMAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables

Create a .env file or set environment variables:

# DiagramAI API Configuration
DIAGRAMAI_API_URL=http://localhost:3000
DIAGRAMAI_API_KEY=your-api-key-here

# Optional: WebSocket URL (if different from API URL)
DIAGRAMAI_WS_URL=ws://localhost:3000

# Optional: Request timeout (milliseconds)
REQUEST_TIMEOUT=30000

# Optional: Enable debug logging
DEBUG=false

API Key Setup

1. Access DiagramAI Settings: Navigate to your DiagramAI instance settings
2. Generate API Key: Create a new API key with appropriate permissions
3. Configure MCP: Add the API key to your Claude Desktop configuration

Required Permissions

• diagrams:create - Create new diagrams
• diagrams:read - Read diagram content
• diagrams:update - Modify diagrams
• diagrams:delete - Delete diagrams
• projects:read - Access project information

Available Tools

Diagram Management

// Create a new diagram
create_diagram({
  title: "My Flowchart",
  type: "reactflow", // or "mermaid"
  content: {...}, // Diagram content
  projectId?: "project-uuid"
})

// Get diagram by ID
get_diagram({
  diagramId: "diagram-uuid"
})

// Update existing diagram
update_diagram({
  diagramId: "diagram-uuid",
  title?: "New Title",
  content?: {...}
})

// Delete diagram
delete_diagram({
  diagramId: "diagram-uuid"
})

// List all diagrams
list_diagrams({
  projectId?: "project-uuid",
  limit?: 10
})

Node and Edge Operations

// Add node to diagram
add_node({
  diagramId: "diagram-uuid",
  node: {
    id: "node-1",
    type: "process",
    position: { x: 100, y: 100 },
    data: { label: "Process Step" }
  }
})

// Add edge between nodes
add_edge({
  diagramId: "diagram-uuid",
  edge: {
    id: "edge-1",
    source: "node-1",
    target: "node-2"
  }
})

Development

Building

npm run build

Running in Development

npm run dev

Testing

npm test

Troubleshooting

Common Issues

Connection Failed

• Verify DiagramAI is running and accessible
• Check API URL and port configuration
• Ensure API key is valid and has required permissions

Authentication Errors

• Verify API key format (should start with da_)
• Check API key permissions in DiagramAI settings
• Ensure API key hasn't expired

Tool Execution Errors

• Check diagram ID format (should be valid UUID)
• Verify user has access to the specified diagram
• Check network connectivity to DiagramAI instance

Debug Mode

Enable debug logging by setting DEBUG=true in your environment variables.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• GitHub Issues
• DiagramAI Documentation
• Model Context Protocol