Plotnine MCP

🚀 Plotnine MCP Server

📊 Plotnine MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，它借助 plotnine 将 R 语言中广受欢迎的 ggplot2 图形语法引入 Python，让你能够通过自然语言，利用 AI 实现数据可视化。通过与 AI 聊天，你可以轻松创建出达到出版级质量的统计图形。这个模块化的 MCP 服务器允许 Claude 等 AI 助手通过图形语法范式组合图层，生成高度可定制的可视化效果。

✨ 主要特性

核心可视化功能

• 🎨 多层绘图：在单个图表中组合多种几何图形（如散点图 + 趋势线、箱线图 + 抖动点等）。
• 图形语法：运用美学、几何图形、比例尺、主题、分面和坐标等元素来构建图表。
• 20 多种几何图形类型：包括点、线、条形图、直方图、箱线图、小提琴图等。
• 多数据源支持：可从文件（CSV、JSON、Parquet、Excel）、URL 或内联 JSON 加载数据。
• 多输出格式：支持 PNG、PDF、SVG 格式，且可配置尺寸和 DPI。

智能特性（新功能！）

• 📋 9 种绘图模板：为常见模式（时间序列、带趋势的散点图、分布比较等）提供预配置模板。
• 🤖 AI 模板建议：分析你的数据并推荐合适的图表类型。
• 🎨 21 种调色板：包含色盲友好、科学、分类、企业、顺序和发散等多种调色板。
• 📊 数据预览：在绘图前检查数据并提供全面摘要。
• 🎯 智能错误信息：通过模糊匹配为列名、几何类型和主题中的拼写错误提供修正建议。
• 💾 配置导出/导入：将绘图配置保存为 JSON 文件，以便重复使用。

数据处理（新功能！）

• 🔄 12 种数据转换：包括过滤、分组汇总、排序、选择、重命名、变异、删除缺失值、填充缺失值、采样、去重、滚动计算、透视等。
• ⚡ 批量处理：一次操作创建多个图表。
• 🔗 链式转换：按顺序应用多个转换。

主题与定制

• 灵活的主题设置：内置主题，提供丰富的自定义选项。
• 统计转换：添加平滑、分箱、密度估计和汇总等功能。
• 分面绘图：使用包装或网格布局按分类变量拆分图表。

📦 安装指南

1. 克隆或下载本仓库

cd plotnine-mcp

2. 安装依赖

使用 pip 安装：

pip install -e .

若需要完整功能（支持 Parquet 和 Excel）：

pip install -e ".[full]"

3. 配置 MCP 客户端

查找安装路径

首先，找到 plotnine-mcp 命令的安装位置：

which plotnine-mcp

这将显示类似 /path/to/python/bin/plotnine-mcp 的路径。在以下配置中使用此完整路径。

Claude Desktop

将服务器添加到 Claude Desktop 配置文件中：

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

推荐（使用入口点）：

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

替代方法（使用 python -m）：

{
  "mcpServers": {
    "plotnine": {
      "command": "python",
      "args": ["-m", "plotnine_mcp.server"]
    }
  }
}

如果你在虚拟环境中安装，请替换为完整路径：

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/venv/bin/plotnine-mcp",
      "args": []
    }
  }
}

Cursor

推荐方法：通过项目中的 .cursor/mcp.json 进行配置：

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

替代方法：打开命令面板 (Cmd/Ctrl+Shift+P) 并搜索 "Preferences: Open User Settings (JSON)"，添加到 Cursor 全局设置中：

{
  "mcp.servers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

使用 python -m 的替代方法：

{
  "mcpServers": {
    "plotnine": {
      "command": "python",
      "args": ["-m", "plotnine_mcp.server"]
    }
  }
}

VSCode（使用 Cline/Roo-Cline）

添加到 VSCode MCP 设置文件中：

• macOS/Linux：~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
• Windows：%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

对于 VSCode 中的其他 MCP 客户端，请参考其特定文档进行 MCP 服务器配置。

4. 重启应用程序

重启 Claude Desktop、Cursor 或 VSCode 以使更改生效。此时，plotnine MCP 服务器应该可用了！

💻 使用示例

基础示例

Create a scatter plot from data.csv with x=age and y=height

高级示例

Create a line plot from sales_data.csv showing:
- x: date, y: revenue, color by region
- Use a minimal theme with figure size 12x6
- Add a smooth trend line
- Facet by product category
- Label the plot "Q4 Sales Performance"
- Save as PDF

可用工具（共 11 种）

核心工具

create_plot

创建完全可定制的 plotnine 可视化图表。

必需参数：

• data_source：数据源配置
• aes：美学映射（列名）
• geom 或 geoms：几何图形规范

可选参数：

• scales：比例尺配置数组
• theme：主题配置
• facets：分面配置
• labels：图表标签（标题、x 轴、y 轴、图例、副标题）
• coords：坐标系配置
• stats：统计转换
• transforms：数据转换（新功能！）
• output：输出配置（格式、大小、DPI、目录）

list_geom_types

列出所有 20 多种可用的几何图形类型及其描述。

数据工具（新功能！）

preview_data

在创建图表前预览和检查数据。返回数据集形状、列类型、前几行、统计信息和缺失值。

参数：

• data_source：数据源配置
• rows：预览的行数（默认值：5）

模板工具（新功能！）

list_plot_templates

列出所有 9 种可用的绘图模板及其描述：

• time_series
• scatter_with_trend
• distribution_comparison
• category_breakdown
• correlation_heatmap
• boxplot_comparison
• multi_line
• histogram_with_density
• before_after

create_plot_from_template

使用预定义模板创建图表。只需提供数据和美学映射，模板将处理其余部分。

参数：

• template_name：模板名称
• data_source：数据源配置
• aes：美学映射
• labels：可选标签
• output：可选输出配置
• overrides：可选的模板设置覆盖项

样式工具（新功能！）

list_themes

列出所有可用的图表主题及其描述和自定义选项。

list_color_palettes

列出 6 个类别中的 21 种调色板：

• 色盲友好（3 种调色板）
• 科学（4 种调色板）
• 分类（4 种调色板）
• 企业（3 种调色板）
• 顺序（4 种调色板）
• 发散（3 种调色板）

参数：

• category：可选的类别过滤器

配置工具

export_plot_config

将绘图配置导出为 JSON 文件，以便重复使用和共享。

参数：

• config：要导出的绘图配置
• filename：输出文件名
• directory：输出目录（默认值：./plot_configs）

import_plot_config

导入并使用保存的绘图配置，可选择覆盖部分参数。

参数：

• config_path：保存的配置文件路径
• overrides：可选的参数覆盖项

批量工具（新功能！）

batch_create_plots

一次操作创建多个图表。非常适合为所有列、成对比较或同一数据的不同可视化生成图表。

参数：

• plots：绘图配置数组

几何图形类型

• point：散点图点
• line：连接点的折线图
• bar：条形图（默认计数）
• col：柱状图（恒等统计）
• histogram：连续数据的直方图
• boxplot：箱线图
• violin：小提琴图
• area：折线下方的填充区域
• density：核密度图
• smooth：平滑条件均值
• jitter：抖动点（减少重叠）
• tile：热力图/瓦片图
• text：文本注释
• errorbar：误差线
• hline/vline/abline：参考线
• path：按顺序连接点的路径
• polygon：填充多边形
• ribbon：区间带

示例

简单散点图

{
  "data_source": {
    "type": "file",
    "path": "./data/iris.csv"
  },
  "aes": {
    "x": "sepal_length",
    "y": "sepal_width",
    "color": "species"
  },
  "geom": {
    "type": "point",
    "params": {"size": 3, "alpha": 0.7}
  }
}

带主题的折线图

{
  "data_source": {
    "type": "url",
    "path": "https://example.com/timeseries.csv"
  },
  "aes": {
    "x": "date",
    "y": "value",
    "color": "category"
  },
  "geom": {
    "type": "line",
    "params": {"size": 1.5}
  },
  "scales": [
    {
      "aesthetic": "x",
      "type": "datetime",
      "params": {"date_breaks": "1 month"}
    }
  ],
  "theme": {
    "base": "minimal",
    "customizations": {
      "figure_size": [12, 6],
      "legend_position": "bottom"
    }
  },
  "labels": {
    "title": "Time Series Analysis",
    "x": "Date",
    "y": "Value"
  }
}

分面箱线图

{
  "data_source": {
    "type": "inline",
    "data": [
      {"group": "A", "category": "X", "value": 10},
      {"group": "A", "category": "Y", "value": 15},
      {"group": "B", "category": "X", "value": 12}
    ]
  },
  "aes": {
    "x": "group",
    "y": "value",
    "fill": "group"
  },
  "geom": {
    "type": "boxplot"
  },
  "facets": {
    "type": "wrap",
    "facets": "~ category"
  },
  "theme": {
    "base": "bw"
  }
}

多层绘图：散点图 + 平滑趋势线

新功能！ 组合多个几何图形创建复杂的可视化图表：

{
  "data_source": {
    "type": "file",
    "path": "./data/measurements.csv"
  },
  "aes": {
    "x": "time",
    "y": "value",
    "color": "sensor"
  },
  "geoms": [
    {
      "type": "point",
      "params": {"size": 2, "alpha": 0.6}
    },
    {
      "type": "smooth",
      "params": {"method": "lm", "se": false}
    }
  ],
  "theme": {
    "base": "minimal",
    "customizations": {"figure_size": [12, 6]}
  },
  "labels": {
    "title": "Sensor Readings with Trend Lines",
    "x": "Time",
    "y": "Measurement"
  }
}

带抖动点的箱线图

同时显示分布摘要和单个数据点：

{
  "data_source": {
    "type": "file",
    "path": "./data/experiment.csv"
  },
  "aes": {
    "x": "treatment",
    "y": "response",
    "fill": "treatment"
  },
  "geoms": [
    {
      "type": "boxplot",
      "params": {"alpha": 0.7}
    },
    {
      "type": "jitter",
      "params": {"width": 0.2, "alpha": 0.5, "size": 1}
    }
  ],
  "theme": {
    "base": "bw"
  },
  "labels": {
    "title": "Treatment Effects with Individual Observations"
  }
}

聊天示例

你可以通过自然语言创建图表：

• "Create a histogram of the 'age' column from users.csv"
• "Make a scatter plot with smooth trend line showing price vs size, colored by category"
• "Plot a line chart from sales.csv with date on x-axis and revenue on y-axis, faceted by region, using a dark theme"
• "Create a violin plot comparing distributions of test scores across different schools"
• "Make a boxplot with individual points overlaid showing temperature by season"
• "Create a scatter plot with a linear trend line for each category, showing the relationship between hours studied and test scores"

使用新工具

• "Preview the data from sales.csv before plotting"
• "What themes are available?"
• "Show me all available plot templates"
• "Suggest appropriate plot types for my data"
• "Create a time series plot using the template"
• "List color palettes in the scientific category"
• "Export this plot configuration so I can reuse it later"
• "Load the plot config from my_config.json and use it with a different dataset"
• "Create a plot from the saved configuration but change the theme to minimal"
• "Create plots for each category in my dataset"（批量处理）
• "Filter the data to show only active users, then create a histogram"（数据转换）

新示例

使用模板

使用模板创建带趋势线的散点图：

"Use the scatter_with_trend template to plot height vs weight from my data"

这将自动创建一个包含以下元素的图表：

• 散点（带透明度）
• 线性回归线
• 置信区间
• 简约主题

使用调色板

"Create a bar chart colored using the colorblind-safe Okabe-Ito palette"

数据转换

"Filter sales data to show only Q4, group by region, sum the revenue, and create a bar chart"

这将在绘图前应用以下转换：

1. 过滤："quarter == 'Q4'"
2. 分组汇总：按地区分组，汇总收入
3. 绘图：结果的条形图

批量处理

"Create histogram plots for all numeric columns in my dataset"

配置选项

主题

可用的基础主题：

• gray（默认）
• bw（黑白）
• minimal
• classic
• dark
• light
• void

比例尺类型

• 位置：连续、离散、对数 10、平方根、日期时间
• 颜色/填充：渐变、离散、Brewer

坐标系

• cartesian（默认）
• flip（交换 x 轴和 y 轴）
• fixed（固定纵横比）
• trans（转换后的坐标）

输出

默认情况下，图表将保存到 ./output 目录，以 PNG 文件形式保存，DPI 为 300。你可以自定义：

• format：png、pdf、svg
• filename：自定义文件名（默认自动生成）
• width/height：尺寸（英寸）
• dpi：光栅格式的分辨率
• directory：输出目录路径

故障排除

"Module not found" 错误

确保你已安装该包：

pip install -e .

Parquet/Excel 支持

安装可选依赖：

pip install -e ".[full]"

"Cannot find data file"

使用绝对路径或相对于 Claude Desktop 运行位置的相对路径。

图表未渲染

检查以下内容：

• aes 中的列名与数据匹配
• 数据类型适合几何图形
• 提供了必需的美学映射（例如，大多数几何图形需要 x 和 y）

开发

运行测试

pytest

代码格式化

black src/
ruff check src/

📄 许可证

MIT

贡献

欢迎贡献！请提交问题或拉取请求。

资源

• plotnine 文档
• MCP 规范
• 图形语法