Sailor

by aj-geddes

Not rated
GitHub

About

Generate and render Mermaid diagrams as images using LLMs.

Details

Author
aj-geddes
Categories
Developer Tools, AI, Knowledge Base

Setup

Install Sailor in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/aj-geddes/sailor

Follow the installation instructions in the repository README, then restart your MCP client.

Sailor combines a beautiful web interface with an MCP (Model Context Protocol) server for generating and rendering Mermaid diagrams. Use the web UI for interactive diagram creation, or integrate with Claude Desktop for AI-powered diagram generation through natural language.

- Modern FastMCP Architecture: 70% less boilerplate code with decorator-based patterns
- Simplified Development: No more stdio_wrapper complexity - FastMCP handles it all
- Faster Startup: ~50% improvement in server initialization time
- Better Type Safety: Native Python type hints throughout
- Cleaner API: Simple@mcp.tool()and@mcp.prompt()decorators
- Dual Transport Support: Built-in stdio and HTTP/SSE transports
- Direct Image Returns: Usereturn_image=trueto get images inline without file downloads

Sailor provides11 tools,11 prompts, and a comprehensive resource library for Mermaid diagram generation.

- 🎨AI-Powered Generation: Generate diagrams using OpenAI or Anthropic APIs
- πŸ”„Live Preview: Real-time rendering with syntax highlighting
- πŸ“‹Copy Functions: Copy both code and rendered images
- 🎯Style Controls: Theme and appearance customization
- βœ…API Key Validation: Instant feedback on key validity

- πŸ“All Mermaid Diagram Types: Flowcharts, sequence, gantt, class, state, ER, pie, mindmap, journey, timeline
- 🎨Multiple Themes: Default, dark, forest, neutral
- ✏️Hand-drawn Look: Optional sketch-style rendering
- πŸ–ΌοΈFlexible Output: PNG with transparent background support
- πŸ€–LLM Integration: Works with Claude Desktop via MCP
- 🐳Fully Containerized: No dependencies needed except Docker
- ⚑FastMCP Architecture: Modern, maintainable codebase with decorators

Choose your preferred way to use Sailor:

git clone https://github.com/aj-geddes/sailor.git cd sailor
cd backend cp .env.example .env # Edit .env with your API keys

Prerequisites: Docker Desktop + Claude Desktop

git clone https://github.com/aj-geddes/sailor.git cd sailor docker build -f Dockerfile.mcp-stdio -t sailor-mcp .

Add the following to your Claude Desktop configuration file:

Windows:%APPDATA%\Claude\claude_desktop_config.json
macOS:~/Library/Application Support/Claude/claude_desktop_config.json
Linux:~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "sailor-mermaid": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "C:\\Users\\YourName\\Pictures:/output", "sailor-mcp" ] } } }

Note: ReplaceC:\\Users\\YourName\\Pictureswith your desired output directory.

Completely close and reopen Claude Desktop to load the new configuration.

Use Sailor without any local installation by connecting to a hosted MCP server.

Configure Claude Desktopto use a remote Sailor instance:

{ "mcpServers": { "sailor-remote": { "transport": { "type": "streamable-http", "url": "https://your-sailor-instance.up.railway.app/mcp" } } } }

- No Docker or local installation required
- Always available, runs 24/7
- Automatic updates and maintenance
- Works from any machine with Claude Desktop

Deploy Your Own:SeeRailway Deployment Guideto host your own remote instance.
- Enter API Key: Provide your OpenAI or Anthropic API key
- Describe Your Diagram: Enter a natural language description
- Generate: Click "Generate Diagram" to create Mermaid code
- Customize: Use style controls to adjust appearance
- Export: Copy the code or image with the copy buttons

Once configured, you can use natural language commands in Claude Desktop:

- "Use sailor-mermaid to create a flowchart showing a login process"
- "Generate a sequence diagram with sailor-mermaid showing API calls"
- "Create a Gantt chart for a project timeline using sailor-mermaid"
- "Show me examples of Mermaid diagrams with sailor-mermaid"

Images are automatically saved to your configured output directory.

When using Sailor via a remote MCP server (like Railway), the server cannot write to your local filesystem. Usereturn_base64_text=trueto get the image as extractable base64:

# The response includes base64_data which you can save via: echo "<base64_data>" | base64 -d > diagram.png

Interactive wizards to help you create diagrams through guided conversations:

- Themes:default,dark,forest,neutral
- Look:classic,handDrawn
- Background:transparent,white
- Direction:TB(top-bottom),LR(left-right),BT,RL

sailor/ β”œβ”€β”€ backend/ # Web UI Flask application β”‚ β”œβ”€β”€ app.py # Main Flask server β”‚ β”œβ”€β”€ static/ # Frontend files (HTML/CSS/JS) β”‚ β”œβ”€β”€ requirements.txt # Web UI dependencies β”‚ └── .env.example # Environment template β”œβ”€β”€ src/ β”‚ └── sailor_mcp/ # FastMCP server implementation β”‚ β”œβ”€β”€ server.py # Main MCP server with decorators β”‚ β”œβ”€β”€ renderer.py # Mermaid rendering engine β”‚ β”œβ”€β”€ validators.py # Syntax validation β”‚ β”œβ”€β”€ prompts.py # AI prompt templates β”‚ └── mermaid_resources.py # Examples and templates β”œβ”€β”€ tests/ # Comprehensive test suite β”œβ”€β”€ Dockerfile.mcp-stdio # MCP server container β”œβ”€β”€ docker-compose.yml # Multi-service setup β”œβ”€β”€ setup.py # Python package setup (v2.0.0) └── requirements.txt # FastMCP dependencies

Comprehensive documentation is available in thedocs/directory:

- docs/DOCKER.md- Docker deployment, container configuration, and best practices
-
docs/PRODUCTION.md- Production deployment, security hardening, and monitoring
-
docs/README.md- Complete documentation index
-
CLAUDE.md- AI assistant development guide

Development scripts are located in thescripts/directory.

# Setup environment cd backend cp .env.example .env # Edit .env with your API keys # Install dependencies pip install -r requirements.txt # Run Flask development server python app.py # Access at http://localhost:5000
# Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install FastMCP and dependencies pip install fastmcp>=0.5.0 pip install -e . # Install Playwright browsers playwright install chromium # Run tests pytest # Run MCP server with stdio (Claude Desktop) python -m sailor_mcp.server # Run MCP server with HTTP/SSE (Web clients) python -m sailor_mcp.server --http --port 8000
# Run everything with Docker Compose docker-compose up --build # Web UI: http://localhost:5000 # MCP Server: Available for Claude Desktop integration

- Ensure Docker Desktop is running
- Check the image exists:docker images | grep sailor-mcp
- Verify config file location and JSON syntax
- Restart Claude Desktop completely

docker logs $(docker ps -a | grep sailor-mcp | awk '{print $1}')

MIT License - seeLICENSEfile for details.

Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (git checkout -b feature/AmazingFeature)
- Commit your changes (git commit -m 'Add some AmazingFeature')
- Push to the branch (git push origin feature/AmazingFeature)
- Open a Pull Request

- Built withMCP(Model Context Protocol)
- Powered by
Mermaid.jsfor diagram rendering
- Uses
Playwrightfor headless rendering

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Automatically generates documentation for code repositories by analyzing directory structures and code files using the OpenRouter API.

A coding assistant server that provides context-aware code suggestions, documentation integration, and technology detection.

Share your team's Coding Best Practices with Cursor, VS Code, Claude code, Windsurf, JetBrains IDEs and other coding tools supporting remote MCP connection.

Generate draw.io system architecture diagrams from text descriptions using the ZhipuAI large model.

A RAG-based Q&A server using a vector store built from Gemini CLI documentation.

An MCP server for Hierarchical Event Descriptors (HED) that automates sidecar creation and annotation for BIDS event files using LLMs.

Lance is an agent that runs on its own cloud Mac and handles everything on the App Store Connect side of shipping an iOS app. It connects to coding agents like Claude Code and Codex through MCP and takes over the parts they can't do: creating apps on App Store Connect, setting up notifications / widgets, filling out listing metadata, uploading builds to TestFlight, submitting for review, and responding to App Review feedback. Because it has its own Mac, it can also build, run, and test users' apps and capture screenshots.

Provides educational content, model information, and read-only API interactions for Lerian developers.

Integrates LLM applications with documentation sources using the Model Context Protocol.

An MCP server for query generation and documentation assistance using Claude AI.

No reviews yet β€” be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.