plotly MCP

Plotly MCP服务器

MCP（模型上下文协议）服务器，使LLM能够生成Plotly图表。支持所有51种Plotly跟踪类型，包括完整属性传递、多跟踪图表和多面板仪表板。

特性

• 所有Plotly跟踪类型 --散点图、条形图、烛台图、sankey图、choropleth图、指示器和45+更多
• 全部财产通过 --直接接受任何有效的Plotly跟踪或布局属性
• 多轨迹图 --在单个图形上叠加多种轨迹类型
• 仪表板布局 --带有预设的多面板网格(2x2, sidebar等）和自动子地块类型检测
• 实时仪表板 --自动生成的交互式HTML仪表板，带有KPI卡、过滤器、交叉过滤、亮/暗主题和可选的实时数据刷新
• 基于文件的工作流 --一步加载CSV/TSV/Excel/JSON、分析数据和图表
• 结构化错误处理 --错误返回JSON，其中包含LLM可以处理的类型、消息和建议
• 双输出 --HTML（交互式）和/或PNG（静态）输出

安装

python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

环境变量（全部可选）：

MCP客户端设置

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "plotly-charts": {
      "command": "/path/to/plotly_mcp/.venv/bin/plotly-mcp"
    }
  }
}

克劳德代码

claude mcp add plotly-charts /path/to/plotly_mcp/.venv/bin/plotly-mcp

工具

create_chart

创建任何Plotly图表。两种通话约定：

简单（单轨迹）：

{
  "chart_type": "candlestick",
  "data": {
    "x": ["2024-01-01", "2024-01-02"],
    "open": [10, 12], "high": [15, 14],
    "low": [9, 11], "close": [13, 12]
  },
  "layout": {"title": "Stock Price"},
  "output_format": "both"
}

高级（多跟踪）：

{
  "traces": [
    {"type": "scatter", "x": [1, 2, 3], "y": [4, 5, 6], "mode": "lines", "name": "Trend"},
    {"type": "bar", "x": [1, 2, 3], "y": [2, 3, 1], "name": "Volume"}
  ],
  "layout": {"title": "Multi-trace Chart"}
}

create_dashboard

创建带有子图的多面板仪表板：

{
  "panels": [
    {"row": 1, "col": 1, "traces": [{"type": "bar", "x": ["A", "B"], "y": [10, 20]}]},
    {"row": 1, "col": 2, "traces": [{"type": "pie", "labels": ["X", "Y"], "values": [30, 70]}]},
    {"row": 2, "col": 1, "traces": [{"type": "scatter", "x": [1, 2], "y": [3, 4], "mode": "markers"}]},
    {"row": 2, "col": 2, "traces": [{"type": "histogram", "x": [1, 2, 2, 3, 3, 3]}]}
  ],
  "preset": "2x2",
  "layout": {"title": "Dashboard"}
}

可用预设： 2x1, 1x2, 2x2, 2x3, sidebar （70/30列）， header_grid （30/70行）。

analyze_data

加载数据文件并获取包含图表建议的摘要：

{
  "file_path": "/path/to/data.csv"
}

支持CSV、TSV、Excel（.xls/.xlsx）和JSON。

create_chart_from_file

一步加载数据文件并创建图表：

{
  "file_path": "/path/to/sales.csv",
  "chart_type": "bar",
  "x_column": "quarter",
  "y_column": "revenue",
  "group_column": "region",
  "trace_properties": {"marker_color": "steelblue"},
  "output_format": "html"
}

create_live_dashboard

从数据文件自动生成交互式HTML仪表板。分析数据以生成KPI卡、图表、过滤器、交叉过滤和主题切换——所有这些都在一个自包含的HTML文件中。

{
  "file_path": "/path/to/sales.csv",
  "title": "Sales Dashboard",
  "metrics": ["revenue", "profit"],
  "time_column": "date",
  "category_column": "region",
  "theme": "dark"
}

实时数据刷新 --启动本地HTTP服务器，在每次轮询时重新读取源文件：

{
  "file_path": "/path/to/sales.csv",
  "title": "Live Sales",
  "serve": true,
  "refresh_interval": 5,
  "port": 8050
}

特征：

• KPI卡 --自动检测或指定的数字指标显示为摘要卡
• 自动布局 --根据列类型选择的时间序列、条形图、饼图、直方图和数据表
• 下拉过滤器 --每个分类列一个（最多20个唯一值）
• 日期范围筛选器 --对于日期时间列
• 交叉过滤 --单击条形图或饼图切片以筛选所有其他图表
• 主题切换 --在运行时在浅色和深色主题之间切换
• 实时刷新 --通过本地HTTP服务器进行可选轮询(serve: true)

stop_dashboard_server

停止正在运行的实时仪表板服务器：

{
  "port": 8050
}

资源

结构化回报

所有工具都返回JSON success 字段：

{"success": true, "files": ["/path/to/chart.html"], "trace_count": 2, "trace_types": ["scatter", "bar"]}

错误包括类型和可操作的消息：

{"success": false, "error": {"type": "invalid_property", "message": "...", "suggestion": "Did you mean 'marker_color'?"}}

发展

pip install -e ".[dev]"
.venv/bin/python -m pytest tests/ -v

依赖项

• Python>=3.10
• mcp[cli] >= 1.2.0
• plotly >= 5.18.0, \= 2.0.0