金大哥 - plotnine-mcp MCP 详情

article

README

🚀 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"

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

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

批量处理

"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/