plotly-mcp-光标

Name: plotly-mcp-光标
Author: arshlibruh

作者：arshlibruh4 星标更新：2025-08-02

安装使用来源：spider==github.com

项目介绍

Plotly MCP 服务器 - 实施计划

项目概述

目标: 仅用于图形对象的 Plotly MCP 服务器，适用于 Cursor
输出: 从自然语言生成的 HTML 可视化
控制: 所有图表元素的分钟级自定义
范围: 完全覆盖 50 多种 Plotly 轨迹类型

第一阶段状态 ✅

基础完成:

✅ 使用 FastMCP 框架的 MCP 服务器 (SDK 1.2.0+)
✅ 49 种轨迹类型的项目结构
✅ 5 种基本轨迹构建器（散点图、条形图、折线图、饼图、直方图）
✅ 图表组装系统
✅ 布局控制器（轴、样式）
✅ 测试用样本数据生成
✅ Cursor 集成准备就绪

快速开始

1. 安装依赖项

使用 UV（推荐）:

# 如果尚未安装，请安装 UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# 设置项目
cd /Users/arshad/Desktop/personal/code/plotly-mcp-claude
uv sync

使用 pip:

pip install -r requirements.txt

2. 运行 MCP 服务器

cd src
python server.py

3. 添加到 Cursor MCP 设置

在你的 Cursor MCP 配置中添加以下内容:

{
  "mcpServers": {
    "plotly-mcp": {
      "command": "python",
      "args": ["/Users/arshad/Desktop/personal/code/plotly-mcp-claude/src/server.py"]
    }
  }
}

可用工具（第一阶段）

基本轨迹构建器

create_scatter_plot - 散点图，带有标记、线条或两者
create_bar_chart - 垂直/水平条形图，带有文本标签
create_line_chart - 折线图，带有样式和填充选项
create_pie_chart - 饼图/甜甜圈图，带有自定义颜色
create_histogram - 直方图，带有分箱和归一化

工具

create_multi_trace_figure - 初始化多个轨迹的图表
generate_sample_data - 创建测试数据（线性、正弦、随机、类别）

使用示例

散点图

create_scatter_plot(
    x_data=[1, 2, 3, 4, 5],
    y_data=[2, 4, 1, 5, 3],
    colors="red",
    sizes=15,
    mode="markers+lines",
    name="我的数据"
)

条形图

create_bar_chart(
    x_data=["A", "B", "C", "D"],
    y_data=[20, 14, 23, 25],
    colors="blue",
    orientation="v",
    text=["20", "14", "23", "25"],
    name="销售数据"
)

饼图

create_pie_chart(
    labels=["苹果", "橙子", "香蕉"],
    values=[30, 25, 45],
    hole=0.3,  # 甜甜圈图
    textinfo="label+percent"
)

生成测试数据

generate_sample_data(
    data_type="sine",
    size=100,
    noise=0.1
)

架构

plotly-mcp-claude/
├── src/
│   ├── server.py              # 主 MCP 服务器 (FastMCP)
│   ├── traces/                # 所有轨迹构建器 (5/49 完成)
│   │   └── basic/            # 第一阶段: 散点图、条形图、折线图、饼图、直方图
│   ├── layouts/              # 布局控制器
│   │   ├── axes.py           # X/Y/Z 轴配置
│   │   └── styling.py        # 颜色、字体、边距、图例
│   ├── assembly/             # 图表构建
│   │   └── builder.py        # 组合轨迹 + 布局
│   └── [themes/, nlp/]       # 未来阶段
├── data/                     # 样本数据集 (未来)
├── examples/                 # 使用示例 (未来)
├── tests/                    # 单元测试 (未来)
├── requirements.txt          # Python 依赖项
├── pyproject.toml           # 项目配置
└── README.md                # 本文件

完整的 Plotly 轨迹类型（计划）

第一阶段 ✅ (5/49)

基本图表: 散点图 ✅, 条形图 ✅, 折线图 ✅, 饼图 ✅, 直方图 ✅

第二阶段 📋 (15 种更多类型)

统计图表: 箱型图, 小提琴图, 热力图, 等高线图, 散点矩阵图, 平行坐标图, 平行分类图, 二维直方图
三维图表: 三维散点图, 表面图, 三维网格图, 体积图, 等值面图, 锥图, 流管图

第三阶段 📋 (15 种更多类型)

地理图表: 分层地图, 地图, 地图框, 地理散点图, 地图散点图, 地图框散点图, 密度图, 密度图框
金融图表: K 线图, OHLC 图, 水平瀑布图
层次图表: 树状图, 太阳辐射图, 冰柱图, 桑基图

第四阶段 📋 (14 种更多类型)

极坐标与坐标系: 极坐标散点图, 极坐标快速散点图, 斯密斯图, 三元散点图, 地毯图, 地毯散点图
专用图表: 漏斗图, 漏斗面积图, 指标图, 图像, 表格
附加: 极坐标条形图, 二维直方图轮廓图, 地毯等高线图

总计: 计划 49 种轨迹构建器

实施时间表

第一阶段 ✅ 基础 (5 种基本轨迹) - 已完成
第二阶段 🚧 统计与三维轨迹 (15 种更多类型)
第三阶段 📋 地理与金融轨迹 (15 种更多类型)
第四阶段 📋 剩余轨迹及完整布局 (14 种更多类型)
第五阶段 📋 主题系统 (科幻、企业、暗主题)
第六阶段 📋 自然语言接口

技术细节

MCP 服务器特性

使用 MCP Python SDK 1.2.0+ 构建
FastMCP 框架便于工具定义
全程使用 异步/等待 模式
所有参数带有 类型提示
带有详细消息的 错误处理
日志记录 用于调试

图表特性

嵌入 Plotly.js 的 HTML 输出
交互式 图表（缩放、平移、悬停）
响应式设计 （默认 800x600）
专业样式 （plotly_white 主题）
完全自定义 所有视觉元素

测试

每种轨迹类型返回完整的 HTML，可以：

在浏览器中直接查看
嵌入应用程序
在 Cursor/Claude 接口中显示

第二阶段的下一步

准备好添加统计与三维轨迹：

箱型图 - 四分位数可视化
小提琴图 - 分布形状
热力图 - 二维数据相关性
三维散点图 - 三维点
表面图 - 三维数学函数

贡献

模块化的架构使得添加新的轨迹类型变得容易：

在 src/traces/{category}/ 中创建轨迹构建器
在 src/server.py 中添加工具装饰器
使用样本数据进行测试
更新文档

要求

Python 3.10+
MCP Python SDK 1.2.0+
Plotly 5.0+
现代浏览器 用于查看图表

第一阶段完成 - 实现了 5/49 种轨迹类型 准备好进入第二阶段：统计与三维可视化

为 Claude 生态系统而打造 ❤️