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.

🚀 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

2. Set up the Python environment:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv add -e .

3. 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!