Chhart MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like ChatGPT, Claude, and others to programmatically create flowcharts and Sankey diagrams on chhart.app.

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
  • Quick Start (Public Server)
  • Local Mode (stdio)
  • Remote Mode (StreamableHTTP)
• Available Tools
• Example Conversations
• Development
• How It Works
• Troubleshooting
• Contributing
• Security
• License
• Links

Features

• 🎨 Create Flowcharts - Generate flowcharts using Chhart's intuitive text-based DSL
• 📊 Create Sankey Diagrams - Build Sankey diagrams from flow data
• 📚 Syntax Help - Get comprehensive documentation and examples
• 🔗 Shareable URLs - All diagrams come with shareable chhart.app links
• 🚀 Easy Integration - Works with any MCP-compatible AI assistant
• 🌐 Dual Mode - Run locally (stdio) or remotely (StreamableHTTP)
• ☁️ Cloud Ready - Deploy to Railway, Vercel, or any Node.js hosting
• 🔒 Reliable - Modern StreamableHTTP transport for stable connections

Prerequisites

• Node.js 20 or higher
• npm or yarn
• An MCP-compatible client (Claude Desktop, Cursor, etc.)

Installation

From npm

npm install -g chhart-mcp

Or run directly without installing:

npx chhart-mcp

From Source

# Clone the repository
git clone https://github.com/alwank/chhart_MCP.git
cd chhart_MCP

# Install dependencies
npm install

# Build the project
npm run build

Usage

Quick Start (Public Server)

You can use our managed MCP server without installing anything locally.

Configure your MCP client to connect to the public endpoint:

{
  "mcpServers": {
    "chhart": {
      "url": "https://mcp.chhart.app/mcp"
    }
  }
}

Local Mode (stdio)

For use with Claude Desktop, Cursor, or other local MCP clients:

1. Build the project:

npm run build

2. Add to your MCP client configuration:

For Claude Desktop, edit `claude_desktop_config.json`:

{
     "mcpServers": {
       "chhart": {
         "command": "npx",
         "args": ["-y", "chhart-mcp"]
       }
     }
   }

For Cursor or other clients, see CONFIG_EXAMPLES.md for more examples.

3. Restart your MCP client

Remote Mode (StreamableHTTP)

For deployment to Railway, Vercel, or other cloud platforms, we use the modern StreamableHTTP transport for reliable, stateless communication.

1. Build and start the StreamableHTTP server:

npm run build
   npm run start:streamable

The server will start on port 3000 (or the port specified in `PORT` environment variable).

2. Configure your MCP client to connect to the remote endpoint:

{
     "mcpServers": {
       "chhart": {
         "url": "https://your-deployment-url.com/mcp"
       }
     }
   }

3. Deploy to Railway:

See the Railway Deployment Guide for detailed instructions.

Why StreamableHTTP?

We migrated from SSE to StreamableHTTP transport for better reliability:

Legacy SSE Mode

The SSE transport is still available but deprecated:

npm run start:sse  # Not recommended for production

Available Tools

`create_flowchart`

Creates a flowchart using Chhart's text-based DSL.

Parameters:

• `content` (string, required) - Flowchart content in Chhart DSL format
• `title` (string, optional) - Title for the flowchart

Example:

{
  "content": "Start\n  Process Step\n    Decision? [shape=diamond]\n      Yes\n        Action\n        End\n      No\n        Skip\n        End",
  "title": "Simple Workflow"
}

`create_sankey`

Creates a Sankey diagram showing flows between nodes.

Parameters:

• `content` (string, required) - Sankey diagram content in Chhart DSL format
• `title` (string, optional) - Title for the diagram

Example:

{
  "content": "Revenue [value=100]\n  Costs [value=40]\n    Salaries [value=25]\n    Operations [value=15]\n  Profit [value=60]",
  "title": "Budget Flow"
}

`get_syntax_help`

Returns documentation and examples for Chhart syntax.

Parameters:

• `type` (enum, optional) - `'flowchart'`, `'sankey'`, or `'all'` (default: `'all'`)

Example Conversations

Once configured, you can ask your AI assistant:

> "Create a flowchart showing a user login process with email verification"

> "Create a Sankey diagram showing how $100 of revenue splits into costs, taxes, and profit"

> "Show me the syntax for creating flowcharts in Chhart"

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Run locally (stdio mode)
npm start

# Run StreamableHTTP server (recommended for remote access)
npm run start:streamable

# Run SSE server (legacy, deprecated)
npm run start:sse

Project Structure

chhart_MCP/
├── src/
│   ├── index.ts              # Main entry point (stdio mode)
│   ├── server-streamable.ts  # StreamableHTTP server (recommended)
│   ├── server-sse.ts         # SSE server (legacy)
│   ├── tools/                # MCP tool implementations
│   ├── utils/                # Utility functions
│   └── transports/           # Transport implementations
│       ├── streamable.ts     # StreamableHTTP transport
│       └── sse.ts            # SSE transport (legacy)
├── dist/                     # Compiled JavaScript (generated)
└── docs/                     # Documentation files

How It Works

The MCP server generates shareable URLs by encoding chart data into the URL hash, leveraging chhart.app's existing URL-based sharing feature. This means:

• ✅ No backend API required
• ✅ Charts are fully client-side
• ✅ URLs work immediately without storage
• ✅ Charts can be edited on chhart.app
• ✅ Privacy-friendly (data stays in the URL)

Troubleshooting

"Command not found" or "Module not found"

• Ensure you've run `npm install` and `npm run build`
• Verify the path in your MCP client configuration is absolute
• Check that Node.js 20+ is installed: `node --version`

Connection Issues

"connection closed: EOF" or similar errors:

• If using remote mode, ensure you're using StreamableHTTP transport (`npm run start:streamable`)
• The legacy SSE transport is deprecated and may have stability issues
• Verify the server is running: check the health endpoint at `http://localhost:3000/health`
• Check firewall settings if deploying remotely
• Ensure CORS is properly configured for your domain

Client configuration:

• StreamableHTTP clients use `application/json` requests to `/mcp`
• Legacy SSE clients require `text/event-stream` for the `/mcp` stream and JSON for `/messages`
• Ensure the URL points to the `/mcp` endpoint

Charts Not Loading

• Verify the generated URL is complete and not truncated
• Check browser console for errors
• Try opening the URL directly in a browser
• Very large diagrams may exceed URL length limits (typically 2000 characters)

TypeScript Build Errors

• Ensure you're using Node.js 20+
• Delete `node_modules` and `dist`, then run `npm install` and `npm run build`
• Check for TypeScript version compatibility

For more help, see CONTRIBUTING.md or open an issue.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Development setup
• Coding standards

Security

For security concerns, please see our Security Policy. Do not open public issues for security vulnerabilities.

License

MIT License - see LICENSE for details.

Copyright (c) 2026 Chhart.app

Links

• Chhart.app - Create and share diagrams
• Model Context Protocol - Learn about MCP
• Documentation - Additional guides and examples
• Changelog - Version history and updates
• Issues - Report bugs or request features