vchart-mcp-server
Officialby VisActor
README.md
<div align="center">
<a href="https://github.com/VisActor#gh-light-mode-only" target="_blank">
<img alt="VisActor Logo" width="200" src="https://github.com/VisActor/.github/blob/main/profile/logo_500_200_light.svg"/>
</a>
<a href="https://github.com/VisActor#gh-dark-mode-only" target="_blank">
<img alt="VisActor Logo" width="200" src="https://github.com/VisActor/.github/blob/main/profile/logo_500_200_dark.svg"/>
</a>
</div>
<div align="center">
<h1>vchart-mcp-server</h1>
</div>
<div align="center">
A Model Context Protocol (MCP) server for the [@visactor/vchart](https://github.com/VisActor/VChart) that enables AI assistants to generate interactive charts and visualizations.
[](https://modelcontextprotocol.io/)
[](https://www.npmjs.com/package/@visactor/vchart-mcp-server)
[](https://www.npmjs.com/package/@visactor/vchart-mcp-server)
[](https://smithery.ai/server/@visactor/vchart-mcp-server)
</div>
<div align="center">
English | [简体中文](./README.zh-CN.md)
</div>
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Chart Output Formats](#chart-output-formats)
- [Common Parameters Supported by All Charts](#common-parameters-supported-by-all-charts)
- [Supported Chart Types and Tools](#supported-chart-types-and-tools)
- [`generate_cartesian_chart`](#generate_cartesian_chart)
- [`generate_polar_chart`](#generate_polar_chart)
- [`generate_hierarchical_chart`](#generate_hierarchical_chart)
- [`generate_progress_chart`](#generate_progress_chart)
- [`generate_wordcloud_venn`](#generate_wordcloud_venn)
- [`generate_range_column_chart`](#generate_range_column_chart)
- [`generate_dual_axis_chart`](#generate_dual_axis_chart)
- [`generate_scatter_chart`](#generate_scatter_chart)
- [`generate_sankey_chart`](#generate_sankey_chart)
- [`generate_heatmap_chart`](#generate_heatmap_chart)
- [Usage](#usage)
- [MacOS](#macos)
- [Windows](#windows)
- [Installing via Smithery](#installing-via-smithery)
- [Running with SSE or Streamable Transport](#running-with-sse-or-streamable-transport)
- [Install and Start](#install-and-start)
- [Other CLI Options](#other-cli-options)
- [Example Usage in AI Conversations](#example-usage-in-ai-conversations)
- [Development](#development)
- [Prerequisites](#prerequisites)
- [Build](#build)
- [Development Mode (Auto Rebuild)](#development-mode-auto-rebuild)
- [Testing](#testing)
- [Debugging](#debugging)
- [Testing in AI Editors](#testing-in-ai-editors)
- [Environment Variables](#environment-variables)
- [Private Deployment](#private-deployment)
- [License](#license)
- [Contributing](#contributing)
- [Related Projects](#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
```json
{
"mcpServers": {
"vchart-mcp-server": {
"command": "npx",
"args": ["-y", "@visactor/vchart-mcp-server"]
}
}
}
```
### Windows
```json
{
"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](https://smithery.ai/server/@VisActor/vchart-mcp-server):
```bash
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:
```bash
npm install -g @visactor/vchart-mcp-server
```
Start the server:
```bash
# 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
```bash
npm run build
```
### Development Mode (Auto Rebuild)
```bash
npm run watch
```
### Testing
```bash
# 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:
```bash
npm run inspector
```
### Testing in AI Editors
To test the MCP server in an AI editor, use the following configuration:
```json
{
"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](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
<a href="https://gitdata.xuanhun520.com/#VisActor/vchart-mcp-server&Date">
<picture >
<source media="(prefers-color-scheme: dark) and (max-width: 800px)" srcset="https://gitdata.xuanhun520.com/api/starimg?repos=VisActor/vchart-mcp-server&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light) and (max-width: 800px)" srcset="https://gitdata.xuanhun520.com/api/starimg?repos=VisActor/vchart-mcp-server&type=Date&theme=light" />
<img style="width: 800px; height: 533px;" alt="Star History Chart" src="https://gitdata.xuanhun520.com/api/starimg?repos=VisActor/vchart-mcp-server&type=Date&theme=dark" />
</picture>
</a>
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
## Related Projects
- [VChart](https://github.com/VisActor/VChart) - Underlying visualization library
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification
TDQS
A3.6/5.0
Scored across 10 tools
Disambiguation5/5
Each tool is clearly distinct, targeting a specific chart type or visualization method (e.g., Cartesian, heatmap, hierarchical, Sankey). The descriptions precisely differentiate purposes, such as trend analysis for Cartesian charts versus flow relationships for Sankey diagrams, leaving no ambiguity for selection.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern with 'generate_' as the prefix (e.g., generate_cartesian_chart, generate_heatmap_chart). This uniform naming convention makes the tool set predictable and easy to navigate for agents.
Tool Count5/5
With 10 tools, the server is well-scoped for chart generation, covering a comprehensive range of visualization types from basic charts like scatter and bar to specialized ones like Sankey and word clouds. Each tool earns its place without redundancy or excessive bloat.
Completeness5/5
The tool set provides complete coverage for data visualization, including common chart types (Cartesian, scatter, polar), specialized visualizations (heatmap, hierarchical, Sankey), and utility charts (progress, word cloud/Venn). There are no obvious gaps; agents can handle diverse visualization needs without dead ends.
Maintenance
ActivityInactive
ResponsivenessNo issues