vchart-mcp-server

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

MCP Server npm Version npm License

English | 简体中文

Related MCP server: MCP Server Chart

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>" } } } }

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

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