ai-mcp-chart-vis

开箱即用的 MCP 图表服务，支持 26+ 种图表类型。 自动启动私有渲染服务，无需手动操作任何进程。

兼容 Cursor、Claude Desktop、VS Code + Cline 等任意支持 MCP 的 AI 客户端。

---

快速安装

Cursor

打开 Cursor Settings → MCP，添加以下配置：

{
  "ai-mcp-chart-vis": {
    "command": "npx",
    "args": ["-y", "github:yanbober/ai-mcp-chart-vis"]
  }
}

Claude Desktop

编辑配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ai-mcp-chart-vis": {
      "command": "npx",
      "args": ["-y", "github:yanbober/ai-mcp-chart-vis"]
    }
  }
}

VS Code + Cline

在 VS Code 设置（Ctrl+,）中搜索 cline.mcp，编辑 settings.json：

{
  "cline.mcp.mcpServers": {
    "ai-mcp-chart-vis": {
      "command": "npx",
      "args": ["-y", "github:yanbober/ai-mcp-chart-vis"]
    }
  }
}

配置完成即可使用，无需 clone 代码、无需 npm install、无需配置环境变量。

---

图片存储位置

每次 AI 生成图表时，PNG 文件会保存在本地。

默认路径：

系统	路径
Windows	C:\Users\你的用户名\.ai-mcp-chart-vis\output\
macOS / Linux	~/.ai-mcp-chart-vis/output/

图片文件名格式：chart-<时间戳>.png，例如 chart-1772787477665.png

---

环境变量配置

所有配置均通过 MCP 配置中的 "env" 字段设置，无需创建任何配置文件。

变量	说明	默认值
VIS_PORT	渲染服务端口	8888
VIS_OUTPUT_DIR	图片保存目录	~/.ai-mcp-chart-vis/output
VIS_CLEANUP	会话结束后自动删除本次图片	false
VIS_REQUEST_SERVER	渲染 API 完整地址（一般无需设置）	由 VIS_PORT 自动推导

示例：自定义所有配置项

{
  "ai-mcp-chart-vis": {
    "command": "npx",
    "args": ["-y", "github:yanbober/ai-mcp-chart-vis"],
    "env": {
      "VIS_PORT":       "8889",
      "VIS_OUTPUT_DIR": "D:/我的图表",
      "VIS_CLEANUP":    "true"
    }
  }
}

---

端口冲突处理

渲染服务默认占用端口 8888。

端口被占用时，通过 VIS_PORT 换用其他端口：

{
  "ai-mcp-chart-vis": {
    "command": "npx",
    "args": ["-y", "github:yanbober/ai-mcp-chart-vis"],
    "env": { "VIS_PORT": "8889" }
  }
}

同时打开多个 Cursor 窗口？ 无冲突——第二个窗口检测到端口已有服务运行，直接复用，不会重复启动。

---

工作原理

AI 客户端（Cursor / Claude Desktop）
    │  stdio — MCP 协议
    ▼
start-mcp.js                         ← 本包入口
    ├── 启动 vis-server.js            ← 私有渲染服务（:8888）
    │       └── @antv/gpt-vis-ssr    ← 将图表规格渲染为 PNG
    │               └── 图片保存到 VIS_OUTPUT_DIR
    └── 启动 @antv/mcp-server-chart（stdio 模式）
            └── 向 AI 暴露 26 个图表工具

会话结束时：
    ├── VIS_CLEANUP=true → 删除本次会话产生的所有图片
    └── 自动关闭渲染服务

• 首次调用：约 5–15 秒冷启动（下载依赖 + 渲染器初始化）
• 后续调用：即时响应（进程在会话期间保持运行）
• 会话结束：两个进程自动清理，无残留

---

支持的图表类型（26 种）

类别	图表
趋势	折线图、面积图、双轴图
对比	柱状图、条形图、直方图
占比	饼图、矩形树图
分布	散点图、箱线图、小提琴图
流向	桑基图、漏斗图、网络关系图
地理	地区分布图、标记地图、路径地图（仅中国区域）
层级	组织架构图、思维导图
专项	雷达图、水位图、词云、鱼骨图、流程图、韦恩图、表格

---

系统要求

环境	要求
Node.js	>= 18.0.0
Windows	✅ 开箱即用
macOS	✅ 开箱即用
Linux	需安装 canvas 原生依赖：sudo apt-get install libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

---

版本锁定

使用指定版本（推荐生产环境）：

"args": ["-y", "github:yanbober/ai-mcp-chart-vis#v1.0.0"]

强制更新到最新版本：

npx --force github:yanbober/ai-mcp-chart-vis --version

---

本地开发

git clone https://github.com/yanbober/ai-mcp-chart-vis.git
cd ai-mcp-chart-vis
npm install

# 仅启动渲染服务
npm run vis:start

# 启动完整链路（渲染服务 + MCP stdio）
npm start

---

使用 sample

Cursor 中丢入一个 excel 等文件，chat 输入类似如下内容：

洞察一下这个用户反馈 xlsx，分端帮忙通过你认为最合适的图表呈现下，同时将洞察结果图文生成 md 格式报告，要简单明了，不要长篇大论。
注意：生成的 md 中图表等图片直接同 md 文件一起放到当前项目的 result 目录，md 文件中引用图片使用本地引用。

打开产物 md 文件预览图文并茂效果。

其他使用场景和配合其他工具整合自行探索~

致谢

本项目站在以下优秀开源项目的肩膀上构建，向原作者们致敬 🙏

项目	说明
@antv/gpt-vis-ssr	图表服务端渲染核心，将图表规格转换为 PNG 图片
@antv/mcp-server-chart	MCP 图表工具集，向 AI 暴露 26+ 种图表生成能力

如果你有更多定制需求，欢迎基于上述原项目二次开发，各显神通！ 原项目均遵循 MIT 协议，欢迎 Star、Fork、PR 🚀

---

许可证

MIT