Vchart MCP Server

🚀 vchart-mcp-server

A Model Context Protocol (MCP) server for the @visactor/vchart that enables AI assistants to generate interactive charts and visualizations.

English | 简体中文

🚀 Quick Start

To use in desktop applications (such as Trae, Claude, VSCode, Cline, Cherry Studio, Cursor, etc.), add the following MCP server configuration:

MacOS

{
  "mcpServers": {
    "vchart-mcp-server": {
      "command": "npx",
      "args": ["-y", "@visactor/vchart-mcp-server"]
    }
  }
}

Windows

{
  "mcpServers": {
    "vchart-mcp-server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@visactor/vchart-mcp-server"]
    }
  }
}

Installing via Smithery

To install vchart-mcp-server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @VisActor/vchart-mcp-server --client claude

✨ Features

Chart Output Formats

Each chart can be generated in multiple formats:

• Image - PNG/JPG image format for embedding (default)
• Spec - VChart spec object for programmatic use
• HTML - Interactive HTML chart for web display

Common Parameters Supported by All Charts

Supported Chart Types and Tools

generate_cartesian_chart

Generates Cartesian coordinate system charts, including area, bar, line, waterfall, funnel, and animated ranking bar charts.

generate_polar_chart

Generates polar coordinate system charts, including radar, rose, and pie charts.

generate_hierarchical_chart

Generates hierarchical charts, including treemap, circle packing, and sunburst charts.

generate_progress_chart

Generates progress charts, including circular, linear, gauge, and liquid charts.

generate_wordcloud_venn

Generates word cloud or Venn diagrams, suitable for displaying keywords and frequencies in text data.

generate_range_column_chart

Generates horizontal range bar charts, suitable for displaying data ranges and comparisons.

generate_dual_axis_chart

Combination chart with two Y axes, for comparing two metrics with different units.

generate_scatter_chart

Displays the relationship between two variables, suitable for discovering patterns and outliers.

generate_sankey_chart

Generates Sankey diagrams.

generate_heatmap_chart

Generates heatmaps, suitable for displaying data density and distribution.

📦 Installation

Install and Start

Install @visactor/vchart-mcp-server globally:

npm install -g @visactor/vchart-mcp-server

Start the server:

# For SSE transport (default endpoint: /sse)
mcp-server-chart --transport sse

# For Streamable transport (default endpoint: /streamable)
mcp-server-chart --transport streamable

Then you can access the server at:

• SSE transport: http://localhost:3001/sse
• Streamable transport: http://localhost:3001/streamable

Other CLI Options

Options:
  -t, --transport <type>   Transport type (stdio, sse, streamable) [default: stdio]
  -p, --port <port>        Port number for HTTP-based transports [default: 3000]
  -e, --endpoint <path>    Endpoint path for HTTP-based transports [default: /message]
  -h, --help               Show this help message

Examples:
  node index.js                                    # Start with stdio transport
  node index.js -t sse -p 3000                     # Start with SSE transport on port 3000
  node index.js -t sse -p 3000 -e /api/sse         # Start with SSE transport on custom endpoint
  node index.js -t streamable -p 3001 -e /stream   # Start with streamable transport on custom endpoint

💻 Usage Examples

Example Usage in AI Conversations

Once configured, you can ask your AI assistant to create charts: "Create an area chart showing monthly sales data"

The assistant will use the generate_cartesian_chart tool with parameters:
- chartType: "area"
- dataTable: your sales data
- xField: "month"
- yField: "sales"

"Generate a dual-axis chart comparing revenue and user growth"

The assistant will use the generate_dual_axis_chart tool with parameters:
- dataTable: your business data
- xField: "time"
- yField: ["revenue", "userGrowth"]

"Show me an interactive HTML bar chart of quarterly performance"

The assistant will use the generate_cartesian_chart tool with parameters:
- chartType: "bar"
- dataTable: your quarterly data
- xField: "quarter"
- yField: "performance"
- output: "html"

"Create a pie chart of product sales share"

The assistant will use the generate_polar_chart tool with parameters:
- chartType: "pie"
- dataTable: your sales data
- categoryField: "product"
- valueField: "sales"

"Draw a scatter plot of height and weight"

The assistant will use the generate_scatter_chart tool with parameters:
- dataTable: your body data
- xField: "height"
- yField: "weight"
- colorField: "gender" (optional)

"Create a radar chart for team skill assessment"

The assistant will use the generate_polar_chart tool with parameters:
- chartType: "radar"
- dataTable: your assessment data
- categoryField: "skill"
- valueField: "score"

"Generate a Sankey diagram showing data flow"

The assistant will use the generate_sankey_chart tool with parameters:
- dataTable: your flow data
- sourceField: "from"
- targetField: "to"
- valueField: "amount"

"Create a heatmap showing data distribution"

The assistant will use the generate_heatmap_chart tool with parameters:
- dataTable: your distribution data
- xField: "x_category"
- yField: "y_category"
- sizeField: "value"

📚 Documentation

Development

Prerequisites

• Node.js version >= 22.7.5

Build

npm run build

Development Mode (Auto Rebuild)

npm run watch

Testing

# Test chart generation
npm run test-tool

# Run MCP Inspector for debugging
npm run inspector

Debugging

Since the MCP server communicates via stdio, debugging can be challenging. Use MCP Inspector for development:

npm run inspector

Testing in AI Editors

To test the MCP server in an AI editor, use the following configuration:

{
  "mcpServers": {
    "vchart-mcp-server": {
      "command": "node",
      "args": ["/Users/path/to/your/project/vchart-mcp-server/build/index.js"]
    }
  }
}

Environment Variables

• VIMD_IMAGE_SERVER - Custom image generation server URL (default: https://vmind.visactor.com/export)

Private Deployment

Currently, images and HTML generated by vchart-mcp-server are produced via https://vmind.visactor.com/export. For private deployment, set the VIMD_IMAGE_SERVER environment variable to specify your own image generation server.

{
  "mcpServers": {
    "mcp-server-chart": {
      "command": "npx",
      "args": [
        "-y",
        "@visactor/vchart-mcp-server"
      ],
      "env": {
        "VIMD_IMAGE_SERVER": "<YOUR_VIS_REQUEST_SERVER>"
      }
    }
  }
}

Image generation service can be deployed privately refer to https://github.com/VisActor/vchart-mcp-server-export.

📄 License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Related Projects

• VChart - Underlying visualization library
• Model Context Protocol - Protocol specification