Vchart MCP Server

🚀 vchart-mcp-server

vchart-mcp-server 是一个适用于 @visactor/vchart 的模型上下文协议（MCP）服务器，它能让 AI 助手生成交互式图表和可视化内容。

English | 简体中文

🚀 快速开始

若要在桌面应用程序（如 Trae、Claude、VSCode、Cline、Cherry Studio、Cursor 等）中使用，请添加以下 MCP 服务器配置：

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

通过 Smithery 安装

若要通过 Smithery 为 Claude Desktop 自动安装 vchart-mcp-server，可使用以下命令：

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

✨ 主要特性

图表输出格式

每个图表都能以多种格式生成：

• 图像 - 用于嵌入的 PNG/JPG 图像格式（默认）
• 规格 - 供编程使用的 VChart 规格对象
• HTML - 用于网页展示的交互式 HTML 图表

所有图表支持的通用参数

支持的图表类型和工具

generate_cartesian_chart

生成笛卡尔坐标系图表，包括面积图、条形图、折线图、瀑布图、漏斗图和动画排名条形图。

generate_polar_chart

生成极坐标系图表，包括雷达图、玫瑰图和饼图。

generate_hierarchical_chart

生成层次结构图表，包括树形图、圆形填充图和旭日图。

generate_progress_chart

生成进度图表，包括圆形进度图、线性进度图、仪表盘和液态图。

generate_wordcloud_venn

生成词云或维恩图，适用于展示文本数据中的关键词和频率。

generate_range_column_chart

生成水平范围条形图，适用于展示数据范围和比较。

generate_dual_axis_chart

具有两个 Y 轴的组合图表，用于比较两个不同单位的指标。

generate_scatter_chart

展示两个变量之间的关系，适用于发现模式和异常值。

generate_sankey_chart

生成桑基图。

generate_heatmap_chart

生成热力图，适用于展示数据密度和分布。

💻 使用示例

AI 对话中的使用示例

配置完成后，你可以要求你的 AI 助手创建图表： “创建一个显示月度销售数据的面积图”

助手将使用 generate_cartesian_chart 工具，并使用以下参数：
- chartType: "area"
- dataTable: 你的销售数据
- xField: "month"
- yField: "sales"

“生成一个比较收入和用户增长的双轴图”

助手将使用 generate_dual_axis_chart 工具，并使用以下参数：
- dataTable: 你的业务数据
- xField: "time"
- yField: ["revenue", "userGrowth"]

“展示一个季度绩效的交互式 HTML 条形图”

助手将使用 generate_cartesian_chart 工具，并使用以下参数：
- chartType: "bar"
- dataTable: 你的季度数据
- xField: "quarter"
- yField: "performance"
- output: "html"

“创建一个产品销售份额的饼图”

助手将使用 generate_polar_chart 工具，并使用以下参数：
- chartType: "pie"
- dataTable: 你的销售数据
- categoryField: "product"
- valueField: "sales"

“绘制一个身高和体重的散点图”

助手将使用 generate_scatter_chart 工具，并使用以下参数：
- dataTable: 你的身体数据
- xField: "height"
- yField: "weight"
- colorField: "gender"（可选）

“创建一个用于团队技能评估的雷达图”

助手将使用 generate_polar_chart 工具，并使用以下参数：
- chartType: "radar"
- dataTable: 你的评估数据
- categoryField: "skill"
- valueField: "score"

“生成一个显示数据流的桑基图”

助手将使用 generate_sankey_chart 工具，并使用以下参数：
- dataTable: 你的流数据
- sourceField: "from"
- targetField: "to"
- valueField: "amount"

“创建一个显示数据分布的热力图”

助手将使用 generate_heatmap_chart 工具，并使用以下参数：
- dataTable: 你的分布数据
- xField: "x_category"
- yField: "y_category"
- sizeField: "value"

📚 详细文档

使用 SSE 或可流式传输协议运行

安装并启动

全局安装 @visactor/vchart-mcp-server：

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

启动服务器：

# 对于 SSE 传输（默认端点：/sse）
mcp-server-chart --transport sse

# 对于可流式传输（默认端点：/streamable）
mcp-server-chart --transport streamable

然后你可以通过以下地址访问服务器：

• SSE 传输：http://localhost:3001/sse
• 可流式传输：http://localhost:3001/streamable

其他 CLI 选项

选项:
  -t, --transport <type>   传输类型 (stdio, sse, streamable) [默认值: stdio]
  -p, --port <port>        基于 HTTP 的传输的端口号 [默认值: 3000]
  -e, --endpoint <path>    基于 HTTP 的传输的端点路径 [默认值: /message]
  -h, --help               显示此帮助信息

示例:
  node index.js                                    # 使用 stdio 传输启动
  node index.js -t sse -p 3000                     # 使用 SSE 传输在端口 3000 上启动
  node index.js -t sse -p 3000 -e /api/sse         # 使用 SSE 传输在自定义端点上启动
  node index.js -t streamable -p 3001 -e /stream   # 使用可流式传输在自定义端点上启动

🔧 技术细节

开发

前提条件

• Node.js 版本 >= 22.7.5

构建

npm run build

开发模式（自动重建）

npm run watch

测试

# 测试图表生成
npm run test-tool

# 运行 MCP Inspector 进行调试
npm run inspector

调试

由于 MCP 服务器通过标准输入输出进行通信，调试可能具有挑战性。可使用 MCP Inspector 进行开发：

npm run inspector

在 AI 编辑器中测试

若要在 AI 编辑器中测试 MCP 服务器，请使用以下配置：

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

环境变量

• VIMD_IMAGE_SERVER - 自定义图像生成服务器 URL（默认：https://vmind.visactor.com/export）

私有部署

目前，vchart-mcp-server 生成的图像和 HTML 是通过 https://vmind.visactor.com/export 生成的。对于私有部署，可设置 VIMD_IMAGE_SERVER 环境变量来指定你自己的图像生成服务器。

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

图像生成服务可参考 https://github.com/VisActor/vchart-mcp-server-export 进行私有部署。

📄 许可证

本项目采用 MIT 许可证。

贡献

欢迎贡献！请随时提交问题和拉取请求。

相关项目

• VChart - 底层可视化库
• Model Context Protocol - 协议规范