Table of Contents

• Table of Contents
• Features
  • Chart Output Formats
  • Common Parameters Supported by All Charts
  • Supported Chart Types and Tools
    • generate_cartesian_chart
    • generate_polar_chart
    • generate_hierarchical_chart
    • generate_progress_chart
    • generate_wordcloud_venn
    • generate_range_column_chart
    • generate_dual_axis_chart
    • generate_scatter_chart
    • generate_sankey_chart
    • generate_heatmap_chart
• Usage
  • MacOS
  • Windows
  • Installing via Smithery
• Running with SSE or Streamable Transport
  • Install and Start
  • Other CLI Options
• Example Usage in AI Conversations
• Development
  • Prerequisites
  • Build
  • Development Mode (Auto Rebuild)
  • Testing
  • Debugging
  • Testing in AI Editors
• Environment Variables
• Private Deployment
• License
• Contributing
• Related Projects

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.

Parameters:

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.

Usage

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

Running with SSE or Streamable Transport

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

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"

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.

Star History

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