mcp-diagram

This MCP Diagram Server provides an automated, persistent environment for creating and managing Mermaid-based diagrams from multiple input formats. It auto-saves diagrams to a local /diagrams library, supports a variety of formats (JSON, CSV, Python code, Markdown, and plain text) and offers a suite of core diagram operations (create, update, get, list, delete) along with conversion tools that transform input content into visual diagrams. You can leverage the integrated template library and multi-format detection to streamline diagram creation, then rely on the automatic persistence to keep your diagrams across sessions. The server exposes tools to convert between formats, load diagrams from storage, and save customized diagrams to new locations, making it suitable for AI-assisted workflows, documentation generation, and data visualization tasks. Typical usage involves creating a diagram or converting an input file, then optionally saving the result to a chosen path or template, with auto-save ensuring your changes are preserved in the library.

Prerequisites:

• Python 3.12 or newer
• uv (the MCP runner for Python) installed
• Optional: Playwright (for rendering) if you need headless rendering capabilities

Installation steps:

1. Clone the repository:

cd /mcp-diagram-server

2. Set up the Python environment and enable auto-seed:

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

4. Start the server via the configured MCP runner (as shown in the mcp_config):

uv run main.py

5. Integrate with Claude Desktop or your MCP client using the provided configuration and ensure the diagrams directory exists at the repository root (diagrams/).

Note: The quick-start configuration shown in the README demonstrates how to wire this server into Claude Desktop with an environment variable for log level. Adjust the directory path to your local clone when deploying.

Tips and common issues:

• Automatic saving writes .mmd files and accompanying _metadata.json to the /diagrams directory. Ensure that path is writable by the server process.
• If you encounter a syntax error while converting a diagram, the system will attempt to remove any dangling parentheses in the underlined code; ensure input formats are clean or rely on the smart detection features.
• When using manual saves (save_diagram), specify custom locations and verify the target path exists to avoid write failures.
• For rendering options, install Playwright if you plan to generate previews or render diagrams in headless environments.
• The library supports a template system with 8+ pre-built templates; explore list_templates to reuse or customize visuals.
• If integrating with other tools, ensure environment variables (like LOG_LEVEL) are set appropriately to control verbosity and diagnostics.