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.

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

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)

Security

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

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

Copy & paste — that's it

npm install -g chhart-mcp

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:

Build the project:
```
npm run build
```
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.
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.

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).

Configure your MCP client to connect to the remote endpoint:

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

Deploy to Railway:

See the Railway Deployment Guide for detailed instructions.

Why StreamableHTTP?

We migrated from SSE to StreamableHTTP transport for better reliability:

Feature	SSE Transport	StreamableHTTP Transport
Connection Type	Long-lived SSE stream	Stateless HTTP requests
Stability	Prone to timeouts	✅ Robust and reliable
Cloud Compatibility	Limited	✅ Excellent
Session Management	Required	Optional (stateless)

Legacy SSE Mode

The SSE transport is still available but deprecated:

npm run start:sse  # Not recommended for production

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.

Licensed under MIT— you can use, modify, and redistribute it under that license's terms.

License

MIT License - see LICENSE for details.

View the full license file on GitHub →

Chhart MCP Server

Table of Contents

Features

Available Tools

create_flowchart

create_sankey

get_syntax_help

Example Conversations

Development

Project Structure

How It Works

Security

Links

Prerequisites

Installation

From npm

From Source

Usage

Quick Start (Public Server)

Local Mode (stdio)

Remote Mode (StreamableHTTP)

Why StreamableHTTP?

Legacy SSE Mode

Troubleshooting

"Command not found" or "Module not found"

Connection Issues

Charts Not Loading

TypeScript Build Errors

License

`create_flowchart`

`create_sankey`

`get_syntax_help`