vchart-mcp-server

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

English | 简体中文

Table of Contents
Features
Usage
Running with SSE or Streamable Transport
- Install and Start
- Other CLI Options
Example Usage in AI Conversations
Development
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

Parameter	Description	Type/Options	Default
`output`	Output format	`"spec"` \| `"image"` \| `"html"`	`"image"`
`width`	Chart width	Number	`500`
`height`	Chart height	Number	`500`
`title`	Chart title	String	Optional
`subTitle`	Chart subtitle	String	Optional
`titleOrient`	Title position	String	Optional
`chartTheme`	Chart theme	String	Optional
`background`	Background color	String	Optional
`colors`	Color palette	Array/String	Optional

Supported Chart Types and Tools

`generate_cartesian_chart`

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

Parameter	Description	Type	Required
`dataTable`	Data object array	Array	Yes
`chartType`	Chart type	`"line"` \| `"area"` \| `"bar"` \| `"waterfall"` \| `"funnel"` \| `"ranking_bar"`	Yes
`xField`	X axis field name	`string`	Yes
`yField`	Y axis field name	`string`	Yes
`colorField`	Color mapping field	`string`	Optional
`timeField`	Time field for animated ranking bar chart	`string`	Optional
`stackOrPercent`	Stack or percent mode	`"stack"` \| `"percent"`	Optional
`transpose`	Display bar chart horizontally (as bar chart)	`boolean`	Optional
`xAxisType`	X axis type	`"band"` \| `"linear"`	Optional
`xAxisOrient`	X axis position	`"top"` \| `"bottom"`	Optional
`xAxisTitle`	X axis title	`string`	Optional
`xAxisHasGrid`	Show X axis grid lines	`boolean`	Optional
`xAxisHasLabel`	Show X axis labels	`boolean`	Optional
`xAxisHasTick`	Show X axis ticks	`boolean`	Optional
`yAxisType`	Y axis type	`"band"` \| `"linear"`	Optional
`yAxisOrient`	Y axis position	`"left"` \| `"right"`	Optional
`yAxisTitle`	Y axis title	`string`	Optional
`yAxisHasGrid`	Show Y axis grid lines	`boolean`	Optional
`yAxisHasLabel`	Show Y axis labels	`boolean`	Optional
`yAxisHasTick`	Show Y axis ticks	`boolean`	Optional

`generate_polar_chart`

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

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	Array	Yes
`chartType`	Chart type	`"radar"` \| `"rose"` \| `"pie"`	Yes
`categoryField`	Category field name	`string`	Yes
`valueField`	Value field name	`string`	Yes
`colorField`	Color mapping field	`string`	Optional
`angleAxisTitle`	Angle axis title	`string`	Optional
`angleAxisHasGrid`	Show angle axis grid lines	`boolean`	Optional
`angleAxisHasLabel`	Show angle axis labels	`boolean`	Optional
`angleAxisHasTick`	Show angle axis ticks	`boolean`	Optional
`angleAxisType`	Angle axis type	`"band"` \| `"linear"`	Optional
`radiusAxisTitle`	Radius axis title	`string`	Optional
`radiusAxisHasGrid`	Show radius axis grid lines	`boolean`	Optional
`radiusAxisHasLabel`	Show radius axis labels	`boolean`	Optional
`radiusAxisHasTick`	Show radius axis ticks	`boolean`	Optional
`radiusAxisType`	Radius axis type	`"band"` \| `"linear"`	Optional

`generate_hierarchical_chart`

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

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	Array	Yes
`chartType`	Chart type	`"sunburst"` \| `"treemap"` \| `"circle_packing"`	Yes
`colorField`	Color mapping field	`string`	Yes
`valueField`	Value mapping field	`string`	Yes

`generate_progress_chart`

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

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	Array	Yes
`chartType`	Chart type	`"linear_progress"` \| `"circular_progress"` \| `"gauge"` \| `"liquid"`	Yes
`valueField`	Progress value field name	`string`	Yes
`colorField`	Color mapping field (optional for liquid, required otherwise)	`string`	Optional

`generate_wordcloud_venn`

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

Parameters:

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	Array	Yes
`chartType`	Chart type	`"wordcloud"` \| `"venn"`	Yes
`colorField`	Text field or Venn set field name	`string`	Yes
`valueField`	Value field name (required for Venn)	`string`	Optional

`generate_range_column_chart`

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

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	`any[]`	Yes
`xField`	Category field name	`string`	Yes
`yField`	Value field names	`[string, string]`	Yes
`colorField`	Color mapping field	`string`	Optional
`xAxisType`	X axis type	`"band"` \| `"linear"`	Optional
`xAxisOrient`	X axis position	`"top"` \| `"bottom"`	Optional
`xAxisTitle`	X axis title	`string`	Optional
`xAxisHasGrid`	Show X axis grid lines	`boolean`	Optional
`xAxisHasLabel`	Show X axis labels	`boolean`	Optional
`xAxisHasTick`	Show X axis ticks	`boolean`	Optional
`yAxisType`	Y axis type	`"band"` \| `"linear"`	Optional
`yAxisOrient`	Y axis position	`"left"` \| `"right"`	Optional
`yAxisTitle`	Y axis title	`string`	Optional
`yAxisHasGrid`	Show Y axis grid lines	`boolean`	Optional
`yAxisHasLabel`	Show Y axis labels	`boolean`	Optional
`yAxisHasTick`	Show Y axis ticks	`boolean`	Optional

`generate_dual_axis_chart`

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

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	`any[]`	Yes
`xField`	X axis field name	`string`	Yes
`yField`	Two Y axis field names	`[string, string]`	Yes
`colorField`	Color mapping field	`string`	Optional
`stackOrPercent`	Stack or percent mode	`"stack"` \| `"percent"`	Optional
`xAxisOrient`	X axis position	`"top"` \| `"bottom"`	Optional
`xAxisTitle`	X axis title	`string`	Optional
`xAxisHasGrid`	Show X axis grid lines	`boolean`	Optional
`xAxisHasLabel`	Show X axis labels	`boolean`	Optional
`xAxisHasTick`	Show X axis ticks	`boolean`	Optional
`leftYAxisTitle`	Left Y axis title	`string`	Optional
`leftYAxisHasGrid`	Left Y axis grid lines	`boolean`	Optional
`leftYAxisHasLabel`	Left Y axis labels	`boolean`	Optional
`leftYAxisHasTick`	Left Y axis ticks	`boolean`	Optional
`rightYAxisTitle`	Right Y axis title	`string`	Optional
`rightYAxisHasGrid`	Right Y axis grid lines	`boolean`	Optional
`rightYAxisHasLabel`	Right Y axis labels	`boolean`	Optional
`rightYAxisHasTick`	Right Y axis ticks	`boolean`	Optional

`generate_scatter_chart`

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

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	`any[]`	Yes
`xField`	X axis field name	`string`	Yes
`yField`	Y axis field name	`string`	Yes
`colorField`	Color mapping field	`string`	Optional
`sizeField`	Size mapping field	`string`	Optional
`xAxisType`	X axis type	`"band"` \| `"linear"`	Optional
`xAxisOrient`	X axis position	`"top"` \| `"bottom"`	Optional
`xAxisTitle`	X axis title	`string`	Optional
`xAxisHasGrid`	Show X axis grid lines	`boolean`	Optional
`xAxisHasLabel`	Show X axis labels	`boolean`	Optional
`xAxisHasTick`	Show X axis ticks	`boolean`	Optional
`yAxisType`	Y axis type	`"band"` \| `"linear"`	Optional
`yAxisOrient`	Y axis position	`"left"` \| `"right"`	Optional
`yAxisTitle`	Y axis title	`string`	Optional
`yAxisHasGrid`	Show Y axis grid lines	`boolean`	Optional
`yAxisHasLabel`	Show Y axis labels	`boolean`	Optional
`yAxisHasTick`	Show Y axis ticks	`boolean`	Optional

`generate_sankey_chart`

Generates Sankey diagrams.

Parameter	Description	Type	Required
`dataTable`	Data object array	`any[]`	Yes
`sourceField`	Source node field	`string`	Yes
`targetField`	Target node field	`string`	Yes
`valueField`	Value field	`string`	Yes

`generate_heatmap_chart`

Generates heatmaps, suitable for displaying data density and distribution.

Parameter	Description	Type/Options	Required
`dataTable`	Data object array	`any[]`	Yes
`xField`	X axis field name	`string`	Yes
`yField`	Y axis field name	`string`	Yes
`sizeField`	Value field name	`string`	Yes
`xAxisType`	X axis type	`"band"` \| `"linear"`	Optional
`xAxisOrient`	X axis position	`"top"` \| `"bottom"`	Optional
`xAxisTitle`	X axis title	`string`	Optional
`xAxisHasGrid`	Show X axis grid lines	`boolean`	Optional
`xAxisHasLabel`	Show X axis labels	`boolean`	Optional
`xAxisHasTick`	Show X axis ticks	`boolean`	Optional
`yAxisType`	Y axis type	`"band"` \| `"linear"`	Optional
`yAxisOrient`	Y axis position	`"left"` \| `"right"`	Optional
`yAxisTitle`	Y axis title	`string`	Optional
`yAxisHasGrid`	Show Y axis grid lines	`boolean`	Optional
`yAxisHasLabel`	Show Y axis labels	`boolean`	Optional
`yAxisHasTick`	Show Y axis ticks	`boolean`	Optional

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.

VChart - Underlying visualization library
Model Context Protocol - Protocol specification