mcp-diagram-server

angrysky56/mcp-diagram-server

3.3

If you are the rightful owner of mcp-diagram-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Diagram Server is a robust tool for creating, managing, and analyzing diagrams using the Model Context Protocol, integrating seamlessly with AI workflows.

Tools
5
Resources
0
Prompts
0

MCP Diagram Server šŸ“Š

A powerful Model Context Protocol (MCP) server for creating, manipulating, and managing Mermaid diagrams with automatic saving and integrated multi-format support. Built with enterprise-grade persistence and designed for seamless AI workflow integration.

šŸŒŸ Key Features

šŸ”„ Automatic Saving & Library System

  • Auto-save on creation/modification - Never lose your work
  • Persistent diagram library stored in /diagrams directory
  • Metadata tracking with creation/modification timestamps
  • Instant load from disk - Diagrams persist across sessions

šŸ“ Integrated Multi-Format Support

  • JSON ā†’ Flowcharts (hierarchical structure visualization)
  • CSV ā†’ Organizational/Relationship charts
  • Python Code ā†’ Class diagrams (automatic AST parsing)
  • Markdown ā†’ Mind maps (hierarchical content mapping)
  • Plain Text ā†’ Structured diagrams (with indentation detection)

šŸŽØ Rich Diagram Types

  • Flowcharts - Process flows and decision trees
  • Sequence Diagrams - Interaction sequences
  • Mind Maps - Concept organization and brainstorming
  • Gantt Charts - Project timelines and scheduling
  • Class Diagrams - Object-oriented system design
  • Entity Relationship - Database schema visualization
  • User Journey Maps - Experience flow mapping
  • Git Graphs - Version control visualization
  • Pie Charts - Data visualization
  • State Diagrams - State machine modeling

šŸ›  Professional Tools

  • Template Library with 8+ pre-built diagram templates
  • Custom save locations in addition to auto-saving
  • Smart format detection with conversion recommendations
  • Resource access for MCP integration
  • Background processing with robust task management

Note: If there is a syntax error converting a diagram remove any () in the underlined code error.

alt text

alt text

alt text

šŸš€ Quick Start- Simply clone the repository and add the following

Claude Desktop Configuration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "diagram-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/your-path-to/mcp-diagram-server",
        "run",
        "main.py"
      ],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Installation- will auto-install with config

  1. Clone the repository:
cd /mcp-diagram-server
  1. Set up the Python environment:
uv venv --python 3.12 --seed
source .venv/bin/activate
uv add -e .
  1. Optional - Install Playwright for rendering:
uv add playwright
uv run playwright install chromium

šŸ“š Available MCP Tools

Core Diagram Operations

  • create_diagram - Create new diagrams with optional templates
  • update_diagram - Modify existing diagram content (auto-saves)
  • get_diagram - Retrieve diagrams from memory or disk
  • list_diagrams - Browse your diagram library
  • delete_diagram - Remove diagrams from memory

Format Conversion Tools

  • convert_format_to_diagram - Universal format converter with auto-detection
  • json_to_flowchart - Convert JSON structures to flowcharts
  • csv_to_org_chart - Convert CSV data to organizational/relationship charts
  • python_to_class_diagram - Convert Python code to class diagrams
  • markdown_to_mindmap - Convert structured markdown to mind maps
  • detect_file_format - Smart format detection with conversion recommendations

Library Management

  • save_diagram - Manual save to custom locations
  • list_templates - Browse available diagram templates
  • Auto-saving - Automatic persistence (always active)

šŸ’” Usage Examples

Universal Format Conversion

convert_format_to_diagram(
    content='{"api": {"users": ["get", "post"], "orders": ["get", "create"]}}',
    target_type="flowchart",
    name="APIStructure"
)

Result: Auto-saved flowchart showing API structure hierarchy

JSON to Flowchart

json_to_flowchart(
    json_content='{"system": {"frontend": "React", "backend": "FastAPI", "db": "PostgreSQL"}}',
    name="SystemArchitecture"
)

Result: Visual flowchart of system components and relationships

CSV to Organizational Chart

csv_to_org_chart(
    csv_content="Name,Role,Department\nAlice,Director,Engineering\nBob,Engineer,Engineering",
    name="TeamStructure"
)

Result: Organizational chart showing team hierarchy

Python Code to Class Diagram

python_to_class_diagram(
    python_code='''
class DatabaseManager:
    def __init__(self):
        self.connection = None
    def connect(self):
        pass
    def query(self, sql):
        pass
''',
    name="DatabaseDesign"
)

Result: UML class diagram from Python code structure

Smart Format Detection

detect_file_format(
    content='class User:\n    def __init__(self):\n        pass',
    filename="models.py"
)

Result: Format identification with conversion recommendations

Create with Template

create_diagram(diagram_type="sequence", use_template=True, name="UserFlow")

Result: Auto-saved sequence diagram template ready for customization

šŸ”§ Understanding Save Systems

Auto-Save (Always Active)

  • When: Every diagram creation and modification
  • Where: /diagrams directory with metadata
  • Format: .mmd file + _metadata.json
  • Purpose: Prevent data loss, maintain library

Manual Save (save_diagram)

  • When: On-demand via tool call
  • Where: Custom locations you specify
  • Format: .mmd file + _metadata.json
  • Purpose: Backups, exports, custom workflows

Both systems work together - Auto-save maintains your library while manual save provides flexibility.

šŸ“ Library Structure

diagrams/
ā”œā”€ā”€ SystemArchitecture_converted_20250824_120000.mmd
ā”œā”€ā”€ SystemArchitecture_converted_20250824_120000_metadata.json
ā”œā”€ā”€ TeamStructure_converted_20250824_130000.mmd
ā”œā”€ā”€ TeamStructure_converted_20250824_130000_metadata.json
ā”œā”€ā”€ UserFlow_diagram_20250824_140000.mmd
ā””ā”€ā”€ UserFlow_diagram_20250824_140000_metadata.json

šŸŽÆ Format Conversion Pipeline

The integrated conversion system handles multiple input formats:

JSON Processing

  • Auto-detects nested JSON structures
  • Generates hierarchical flowcharts showing data relationships
  • Preserves key-value relationships and array structures

CSV Analysis

  • Parses CSV headers and relationships
  • Creates organizational charts or network diagrams
  • Handles employee/role data and relationship matrices

Python AST Parsing

  • Analyzes Python source code structure
  • Extracts classes, methods, and inheritance relationships
  • Generates UML class diagrams with method signatures

Plain Text Intelligence

  • Detects indentation patterns and structure
  • Converts to hierarchical mind maps
  • Processes bullet points and numbered lists

Smart Detection

  • Content analysis for format identification
  • File extension recognition when available
  • Conversion recommendations for optimal diagram types

šŸ›”ļø Enterprise Features

  • Robust Error Handling: Comprehensive exception management
  • Process Management: Background task cleanup and monitoring
  • Data Integrity: Metadata validation and consistency checks
  • Session Persistence: Diagrams survive server restarts
  • Format Validation: Input validation for all supported formats
  • Concurrent Access: Safe multi-client diagram access

šŸ”„ Workflow Integration

Perfect for:

  • AI-Powered Diagramming: Let AI create and modify diagrams from any format
  • Documentation Generation: Convert data structures to visual documentation
  • Process Visualization: Transform workflows into clear diagrams
  • Code Architecture: Generate system diagrams from source code
  • Data Visualization: Convert CSVs and JSON to visual representations
  • Knowledge Mapping: Convert any structured content to mind maps

šŸ“ License

MIT License - See LICENSE file for details

šŸ¤ Contributing

Contributions welcome! The codebase follows modern Python patterns with comprehensive error handling and robust process management.

šŸ™ Acknowledgments

  • Inspired by Drawnix - Open-source whiteboard tool
  • Built with FastMCP
  • Powered by Mermaid diagram syntax
  • Format conversion powered by Python AST parsing and intelligent structure analysis

šŸ“ž Support

For issues or questions, please open an issue on GitHub.

System Requirements: Python 3.10+ | Compatible with Claude Desktop and MCP-enabled clients

šŸš€ Ready to convert any format to diagrams? Start creating visual representations from JSON, CSV, Python code, and more with automatic saving!