Sargoth Mcp

Sargoth Mcp

Created by floor-lickerโ€ขa month ago

MCP Server for the Sargoth Mermaid Editor API

Developer Tools
sargothmermaiddiagram-generatorAIMCP

Sargoth Mermaid Renderer Logo

Sargoth Mermaid Renderer - MCP Server

AI-Powered Diagram Generation - From Natural Language to Professional Visuals

๐ŸŒŸ Powered by Sargoth.xyz - The First & Only Free, No-Account Required Instant Mermaid Renderer on the Web


๐Ÿš€ Transform Ideas into Diagrams with AI

Seamlessly convert your ideas into stunning diagrams using AI. Simply describe your workflow, process, or system in plain English to your LLM assistant, and instantly get professional SVG/PNG diagrams rendered through our high-performance Mermaid engine.

The Perfect AI Workflow:

  • ๐Ÿ’ฌ Describe your diagram needs in natural language to Claude/ChatGPT
  • ๐Ÿค– LLM generates optimized Mermaid code automatically
  • โšก Our MCP server renders beautiful, production-ready visuals instantly
  • ๐Ÿ“ฅ Export as SVG or PNG with custom themes and scaling

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. By creating an MCP server for our Mermaid renderer, we allow AI assistants to:

  • ๐ŸŽจ Generate diagrams in real-time during conversations
  • โœ… Validate Mermaid syntax and suggest improvements
  • ๐Ÿ“š Create visual documentation and explanations
  • ๐Ÿ”„ Help users build complex diagrams step by step

โœจ Features

The MCP server exposes 4 powerful tools:

๐ŸŽจ render_mermaid_svg

Generate SVG diagrams from Mermaid code with theme support.

Parameters:

  • code (required): Mermaid diagram code
  • theme (optional): Theme (modern, classic, dark, minimal)

๐Ÿ–ผ๏ธ render_mermaid_png

Generate PNG images from Mermaid code with scaling.

Parameters:

  • code (required): Mermaid diagram code
  • theme (optional): Theme (modern, classic, dark, minimal)
  • scale (optional): PNG scale factor (1-4, default: 2)

โœ… validate_mermaid

Validate Mermaid syntax and analyze diagram complexity.

Parameters:

  • code (required): Mermaid diagram code to validate

๐Ÿ’ก suggest_mermaid_improvements

Analyze Mermaid code and suggest improvements or fixes.

Parameters:

  • code (required): Mermaid diagram code to analyze
  • diagram_type (optional): Expected diagram type for targeted suggestions

๐Ÿ“ฆ Installation

Prerequisites

  1. Python 3.8+ installed
  2. MCP-compatible AI assistant (Claude Desktop, etc.)
  3. Optional: Local Sargoth Mermaid Renderer API for development (see main project)

Step 1: Install MCP Dependencies

## Install MCP server dependencies
pip install -r requirements.txt

Step 2: Make the Server Executable

chmod +x mcp_server.py

Step 3: Test the Server

Using Production API (Recommended):

## Test with the live production API
python mcp_server.py

Using Local Development API:

## Start your local Mermaid API first
python ../app.py

## In another terminal, test the MCP server with local API
python mcp_server.py --api-url http://localhost:5000

๐Ÿ”Œ Integration with AI Assistants

Claude Desktop

  1. Locate your Claude Desktop config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add the MCP server configuration:

For Production Use (Recommended):

{
  "mcpServers": {
    "mermaid-renderer": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"]
    }
  }
}

For Local Development:

{
  "mcpServers": {
    "mermaid-renderer": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py", "--api-url", "http://localhost:5000"]
    }
  }
}
  1. Restart Claude Desktop

  2. Test the integration:

    • Open a new conversation
    • Ask: โ€œCan you create a flowchart showing a simple user login process?โ€
    • Claude should use the Mermaid tools to generate the diagram!

Other MCP Clients

Production Configuration:

{
  "command": "python",
  "args": ["mcp_server.py"]
}

Local Development Configuration:

{
  "command": "python",
  "args": ["mcp_server.py", "--api-url", "http://localhost:5000"]
}

๐Ÿ’ฌ Usage Examples

Once integrated, you can ask your AI assistant things like:

Basic Diagram Generation

โ€œCreate a sequence diagram showing how a user logs into a web applicationโ€

Validation & Improvement

โ€œCheck this Mermaid code for errors: graph TD A -> Bโ€

Complex Workflows

โ€œGenerate a flowchart for a CI/CD pipeline, then convert it to PNG formatโ€

Educational Content

โ€œCreate a class diagram for a simple e-commerce system and explain each componentโ€

๐ŸŽฏ Example Conversation

You: โ€œCan you create a state diagram for a simple traffic light system?โ€

AI Assistant: Uses render_mermaid_svg tool

stateDiagram-v2
    [*] --> Red
    Red --> Green : Timer
    Green --> Yellow : Timer
    Yellow --> Red : Timer
    Red --> [*]

AI: โ€œIโ€™ve created an SVG diagram of a traffic light state machine! The diagram shows the three states (Red, Green, Yellow) and the timer-based transitions between them. Would you like me to convert this to PNG format or modify the design?โ€

โš™๏ธ API Configuration

Default Behavior

The MCP server uses the production API at https://sargoth.xyz by default. No additional configuration is needed for most users.

Environment Variables

  • MERMAID_API_URL: Override the API base URL (optional)

Command Line Options

python mcp_server.py --help

## Use production API (default)
python mcp_server.py

## Use local development API
python mcp_server.py --api-url http://localhost:5000

## Use custom API endpoint
python mcp_server.py --api-url https://sargoth.xyz

Configuration Examples

Production (Default):

Local Development:

  • Run local API: python ../app.py
  • Use flag: --api-url http://localhost:5000
  • Useful for testing changes

Custom Deployment:

  • Use your own hosted instance
  • Specify with: --api-url https://sargoth.xyz

๐Ÿ”ง Troubleshooting

Server Wonโ€™t Start

  1. Check internet connection (production API requires online access)
  2. Ensure all dependencies are installed: pip install -r requirements.txt
  3. Verify Python version: python --version (needs 3.8+)
  4. For local development, ensure the local Mermaid API is running

AI Assistant Canโ€™t Find Tools

  1. Check the MCP configuration file path
  2. Ensure the server path in config is absolute
  3. Restart your AI assistant after config changes
  4. Check logs for connection errors

Rendering Fails

  1. Production API: Check internet connection and try again
  2. Local API: Verify the API is accessible: curl http://localhost:5000/health
  3. Test with simple Mermaid code first
  4. Check API logs for detailed error messages

Connection Issues

  1. Firewall: Ensure outbound HTTPS connections are allowed
  2. Proxy: Configure proxy settings if behind corporate firewall
  3. Local Development: Verify local API is running on correct port

๐Ÿ”’ Security Considerations

  • Production API: Connects to https://sargoth.xyz over secure HTTPS
  • Network: Requires outbound HTTPS access to sargoth.xyz for production use

๐ŸŽจ Advanced Usage

Custom Themes

The server supports all themes available in your Mermaid renderer:

  • modern (default)
  • classic
  • dark
  • minimal

Batch Processing

While the MCP protocol processes tools individually, you can ask the AI to generate multiple diagrams in sequence.

Integration with Documentation

Use the MCP server to automatically generate diagrams for:

  • Technical documentation
  • Architecture diagrams
  • Process flows
  • Educational materials

๐Ÿค Contributing

This MCP server is part of the Sargoth Mermaid Renderer project. To contribute:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

๐Ÿ“„ License

Same as the main Sargoth Mermaid Renderer project.


Ready to supercharge your AI assistant with diagram generation?

Install the MCP server and start creating beautiful visuals in your conversations! ๐Ÿš€

๐ŸŒŸ Star this repo โ€ข ๐Ÿ“– Main Project โ€ข ๐Ÿ› Report Bug

Prerequisites

  • โ€ขFamiliarity with the server domain
  • โ€ขBasic understanding of related technologies
  • โ€ขKnowledge of Developer Tools

Recommended Server

Details

Created

June 12, 2025

Last Updated

June 12, 2025

Author

floor-licker

Share