Plots MCP Server

A Model Context Protocol (MCP) server for data visualization. It exposes tools to render charts (line, bar, pie, scatter, heatmap, etc.) from data and returns the plot as image/base64 text/mermaid diagram.

为何选择MCP图？

使用Mermaid创建即时、以视觉为主的图表（在Cursor等MCP客户端中直接渲染）
简单的提示即可从原始数据生成图表
通过uvx实现零配置选项，或从PyPI/Docker进行安装
灵活的输出格式：Mermaid（默认）、PNG图像或文本

快速使用

询问你的MCP客户端：“创建一个条形图来展示销售额：A=100，B=150，C=80”
默认输出为Mermaid，因此图表在Cursor中即时渲染

快速入门

PyPI 安装（推荐）

pip install mcp-plots
mcp-plots  # Start the server

对于Cursor用户

安装该软件包： pip install mcp-plots
添加到你的Cursor MCP配置中（~/.cursor/mcp.json):

   {
     "mcpServers": {
       "plots": {
         "command": "mcp-plots",
         "args": ["--transport", "stdio"]
       }
     }
   }

替代方案（通过uvx + PyPI进行零安装）：

   {
     "mcpServers": {
       "plots": {
         "command": "uvx",
         "args": ["mcp-plots", "--transport", "stdio"]
       }
     }
   }

重启光标（或：重置光标）
问： *“创建一个显示销售额的条形图：A=100，B=150，C=80”*

开发安装

uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

文档 → | 快速入门 → | API 参考 →

MCP 注册表

此服务器在MCP注册表标识符下发布 io.github.MR901/mcp-plots您可以通过官方注册表API来发现/验证它：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.MR901/mcp-plots"

此项目的注册表元数据记录在 server.json。

使用Smithery进行安装

这个仓库包含一个 smithery.yaml 便于与Smithery轻松设置集成。

文件： smithery.yaml
文档：https://smithery.ai/docs/config#smitheryyaml

使用 Smithery CLI 进行安装的示例（调整 --client 根据需要，例如。 cursor， claude):

npx -y @smithery/cli install \
  https://raw.githubusercontent.com/mr901/mcp-plots/main/smithery.yaml \
  --client cursor

安装后，您的MCP客户端应该能够使用在（配置文件或文档中）定义的命令通过标准输入输出（stdio）启动服务器 smithery.yaml。

项目布局

src/
  app/                # Server construction and runtime
    server.py
  capabilities/       # MCP tools and prompts
    tools.py
    prompts.py
  visualization/      # Plotting engines and configurations
    chart_config.py
    generator.py

要求

Python 3.10及以上版本
见 requirements.txt

设置路由

uvx（推荐）

无需管理Python环境即可运行MCP服务器的最简单方法：

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

# Or install and run the command
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots

# With custom options
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG

为什么是uvx？

无环境管理自动处理Python依赖项
隔离执行在其自己的虚拟环境中运行
始终最新从仓库拉取最新代码
零设置无需 pip 安装，立即运行
跨平台相同的命令在 Windows、macOS 和 Linux 上均适用

PyPI（传统安装方式）

安装依赖项

pip install -r requirements.txt

运行服务器（HTTP传输，默认端口8000）

python -m src --transport streamable-http --host 0.0.0.0 --port 8000 --log-level INFO

使用标准I/O运行（针对会生成进程的MCP客户端）

python -m src --transport stdio

本地开发（从源代码）

git clone https://github.com/mr901/mcp-plots.git
cd mcp-plots
pip install -e .
python -m src --transport stdio --log-level DEBUG

Docker

docker build -t mcp-plots .
docker run -p 8000:8000 mcp-plots

环境变量（可选）：

MCP_TRANSPORT (streamable-http|stdio) 可翻译为：（可流式传输的HTTP|标准输入输出）
MCP_HOST （默认 0.0.0.0）
MCP_PORT （默认8000）
LOG_LEVEL （默认 INFO）

工具

list_chart_types() → 返回可用的图表类型
list_themes() → 返回可用主题
suggest_fields(sample_rows) → 根据数据样本建议字段角色
render_chart(chart_type, data, field_map, config_overrides?, options?, output_format?) → 返回MCP内容
generate_test_image() → 生成一个测试图像（红色圆圈）以验证MCP图像支持

光标集成

这个MCP服务器是 与Cursor的图像支持完全兼容！当你使用时 render_chart 工具：

图表直接显示在聊天中 - 无需保存文件或打开单独窗口
人工智能可以分析你的图表 - 借助视觉功能的模型可以讨论和解释您的可视化内容
完美的MCP格式 - 使用Cursor所期望的确切base64 PNG格式

服务器返回MCP格式的图像，Cursor需要：

{
  "content": [
    {
      "type": "image", 
      "data": "",
      "mimeType": "image/png"
    }
  ]
}

示例调用（伪代码）：

render_chart(
  chart_type="bar",
  data=[{"category":"A","value":10},{"category":"B","value":20}],
  field_map={"category_field":"category","value_field":"value"},
  config_overrides={"title":"Example Bar","width":800,"height":600,"output_format":"MCP_IMAGE"}
)

返回形状（PNG）：

{
  "status": "success",
  "content": [{"type":"image","data":"","mimeType":"image/png"}]
}

配置

服务器可以通过环境变量或命令行参数进行配置：

服务器设置

MCP_TRANSPORT - 运输类型： streamable-http 或者 stdio （默认： streamable-http)
MCP_HOST - 主机地址（默认： 0.0.0.0)
MCP_PORT - 端口号（默认： 8000)
LOG_LEVEL - 日志级别： DEBUG， INFO， WARNING， ERROR， CRITICAL （默认： INFO）
MCP_DEBUG - 启用调试模式： true 或者 false （默认： false)

图表设置

CHART_DEFAULT_WIDTH - 默认图表宽度（以像素为单位）（默认： 800)
CHART_DEFAULT_HEIGHT - 默认图表高度（以像素为单位）（默认： 600)
CHART_DEFAULT_DPI - 默认图表DPI（默认值： 100)
CHART_MAX_DATA_POINTS - 每个图表的最大数据点数（默认： 10000)

命令行用法

使用uvx（推荐）：

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --help

# Examples:
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --chart-width 1200 --chart-height 800

传统Python：

python -m src --help

# Examples:
python -m src --transport streamable-http --host 0.0.0.0 --port 8000
python -m src --log-level DEBUG --chart-width 1200 --chart-height 800

Docker

构建镜像：

docker build -t mcp-plots .

使用自定义配置运行容器：

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e LOG_LEVEL=INFO \
  -e CHART_DEFAULT_WIDTH=1000 \
  -e CHART_DEFAULT_HEIGHT=700 \
  -e CHART_DEFAULT_DPI=150 \
  -e CHART_MAX_DATA_POINTS=5000 \
  mcp-plots

光标MCP集成

快速设置光标

Plots MCP 服务器旨在与 Cursor 的 MCP 支持无缝协作。以下是集成方法：

1. 添加到Cursor的MCP配置中

将此添加到您的Cursor MCP配置文件中（~/.cursor/mcp.json 或类似表述：

{
  "mcpServers": {
    "plots": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/mr901/mcp-plots.git@main",
        "mcp-plots",
        "--transport", 
        "stdio"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "CHART_DEFAULT_WIDTH": "800",
        "CHART_DEFAULT_HEIGHT": "600"
      }
    }
  }
}

2. 备选方案：HTTP 传输

对于基于HTTP的集成：

{
  "mcpServers": {
    "plots-http": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/mr901/mcp-plots.git@main", 
        "mcp-plots",
        "--transport", 
        "streamable-http",
        "--host", 
        "127.0.0.1",
        "--port", 
        "8000"
      ]
    }
  }
}

3. 本地开发环境设置

对于本地开发（如果您已经克隆了代码）：

{
  "mcpServers": {
    "plots-dev": {
      "command": "python",
      "args": ["-m", "src", "--transport", "stdio"],
      "cwd": "/path/to/mcp-plots",
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

4. 验证集成

添加配置后：

重启光标
检查MCP连接 在Cursor的MCP面板中
用简单图表进行测试：

   Create a bar chart showing sales data: A=100, B=150, C=80

美人鱼——首次尝试（或“初步方法”）

这台服务器优先考虑 默认输出MERMAID 因为：

✅ 在Cursor中即时渲染 - 无需外部查看器
✅ 互动的 - Cursor可以分析和讨论图表
✅（对号，表示正确、确认或完成） 轻便的 - 快速生成和显示
✅ 可扩展的 - 基于矢量，适用于任何缩放级别

原生支持MERMAID的图表类型：

line， bar， pie， area → xychart-beta 格式
histogram → xychart-beta 具有自动分箱功能
funnel → 带有色彩渐变的样式流程图
gauge 带彩色编码值指示器的流程图
sankey 带有源/目标样式的流程图

可用工具

`render_chart`

采用MERMAID优先方法的主图表生成工具。

参数：

chart_type - 图表类型（line， bar， pie， scatter， heatmap等
data - 数据对象列表
field_map - 字段映射（x_field， y_field， category_field等）
config_overrides - 图表配置覆盖
output_format - 输出格式（mermaid \[默认\]， mcp_image， mcp_text)

特殊模式：

chart_type="help" - 显示可用的图表类型和主题
chart_type="suggest" - 分析数据并提出字段映射建议

`configure_preferences`

用于设置用户偏好的交互式配置工具。

参数：

output_format - 默认输出格式（mermaid， mcp_image， mcp_text)
theme - 默认主题（default， dark， seaborn， minimal）
chart_width - 默认图表宽度（以像素为单位）
chart_height - 默认图表高度（以像素为单位）
reset_to_defaults - 将所有偏好设置重置为系统默认值

特点：

持久设置 - 已保存至 ~/.plots_mcp_config.json
实时预览 - 显示带有当前设置的样本图表
覆盖支持 - 使用 config_overrides 对于一次性更改

文档

额外资源

完整的文件记录 - 技术文档中心
快速入门 - 5分钟设置指南
集成指南 - MCP客户端的安装与配置
API 参考文档 - 完整的工具规格及示例
高级指南 - 架构、部署与开发
样本提示 - 立即可用的测试示例

图表示例

基本条形图：

{
  "chart_type": "bar",
  "data": [
    {"category": "Sales", "value": 120},
    {"category": "Marketing", "value": 80},
    {"category": "Support", "value": 60}
  ],
  "field_map": {
    "category_field": "category", 
    "value_field": "value"
  }
}

时间序列折线图：

{
  "chart_type": "line",
  "data": [
    {"date": "2024-01", "revenue": 1000},
    {"date": "2024-02", "revenue": 1200},
    {"date": "2024-03", "revenue": 1100}
  ],
  "field_map": {
    "x_field": "date",
    "y_field": "revenue"
  }
}

漏斗图：

{
  "chart_type": "funnel",
  "data": [
    {"stage": "Awareness", "value": 1000},
    {"stage": "Interest", "value": 500}, 
    {"stage": "Purchase", "value": 100}
  ],
  "field_map": {
    "category_field": "stage",
    "value_field": "value"
  }
}

🔧 配置

环境变量

MCP_TRANSPORT - 运输类型（streamable-http | stdio）
MCP_HOST - 主机地址（默认： 0.0.0.0)
MCP_PORT - 端口号（默认： 8000）
LOG_LEVEL - 日志级别（默认： INFO)
MCP_DEBUG - 启用调试模式（true | false)
CHART_DEFAULT_WIDTH - 默认图表宽度（以像素为单位）（默认值： 800)
CHART_DEFAULT_HEIGHT - 默认图表高度（以像素为单位）（默认值： 600)
CHART_DEFAULT_DPI - 默认图表DPI（默认值： 100)
CHART_MAX_DATA_POINTS - 每个图表的最大数据点数（默认： 10000)

用户偏好设置

个人偏好存储在 ~/.plots_mcp_config.json：

{
  "defaults": {
    "output_format": "mermaid",
    "theme": "default",
    "chart_width": 800,
    "chart_height": 600
  },
  "user_preferences": {
    "output_format": "mcp_image",
    "theme": "dark"
  }
}

🚀 高级用法

自定义主题

可用主题： default， dark， seaborn， minimal， whitegrid， darkgrid， ticks

高分辨率图表

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \
  --chart-width 1920 \
  --chart-height 1080 \
  --chart-dpi 300

性能优化

使用 max_data_points 限制大型数据集
MERMAID的输出速度最快，便于快速可视化
用于高质量静态图像的PNG输出
可缩放矢量图形的SVG输出

🐛 故障排除

常见问题

问题在 Cursor 中图表未显示

解决方案确保 output_format="mermaid" （默认）
检查Cursor中的MCP服务器连接

问题： uvx 命令未找到

解决方案安装 uv： curl -LsSf https://astral.sh/uv/install.sh | sh

问题端口已被使用

解决方案使用不同的端口： --port 8001

问题大型数据集处理缓慢

解决方案示例数据或增加 --max-data-points

调试模式

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \
  --debug \
  --log-level DEBUG

📝 笔记

在容器中，Matplotlib 以无头模式（Agg 后端）运行
对于大型数据集，请对数据进行抽样以评估其响应性
图表的默认设置可以通过每次请求进行覆盖 config_overrides
MERMAID图表在Cursor中即时渲染，提供最佳用户体验
用户偏好在会话之间持续存在，并默认适用于所有图表

MCP Plots

快速接入

详细介绍

为何选择MCP图？

快速使用

快速入门

PyPI 安装（推荐）

对于Cursor用户

开发安装

MCP 注册表

使用Smithery进行安装

项目布局

要求

设置路由

uvx（推荐）

PyPI（传统安装方式）

本地开发（从源代码）

Docker

工具

光标集成

配置

服务器设置

图表设置

命令行用法

Docker

光标MCP集成

快速设置光标

1. 添加到Cursor的MCP配置中

2. 备选方案：HTTP 传输

3. 本地开发环境设置

4. 验证集成

美人鱼——首次尝试（或“初步方法”）

可用工具

render_chart

configure_preferences

文档

额外资源

图表示例

🔧 配置

环境变量

用户偏好设置

🚀 高级用法

自定义主题

高分辨率图表

性能优化

🐛 故障排除

常见问题

调试模式

📝 笔记

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`render_chart`

`configure_preferences`