使用说明

MCP数据科学

提供LLM的MCP服务器（模型上下文协议） 102工具 完整的数据科学管道。加载、检查、清理、转换、编码、可视化、分析数据集、训练ML模型、选择特征、处理日期时间操作、运行统计测试、解释模型、执行聚类和降维——所有这些都是通过自然语言完成的。内建 代理工作流程指南 有13个阶段的管道、决策框架和常见的陷阱警告。零配置——将任何兼容MCP的客户端指向服务器并开始分析数据。

动机

数据科学工作流程需要数十个重复步骤：加载CSV、检查缺失值、编码类别、训练模型、评估结果。 MCP Data Science将整个管道封装到一个服务器中，任何LLM代理都可以端到端地驱动该服务器——没有笔记本电脑，没有样板，没有上下文切换。

阶段	工具	它涵盖了什么
加载中	11	CSV、Excel、Parquet、合并、枢轴、融化、concat
检查	9	头部、尾部、信息、统计数据、质量报告、分析
清洁	9	重复、缺失值、异常值、过滤、合并
转变	9	计算列、日志转换、规范化、字符串清理
编码	4	一个热点、目标、标签、频率编码
可视化	14	柱状图、散点图、方框图、小提琴图、QQ图、相关矩阵图、热图
分析	8	相关性、异常值、组聚合、交叉表
建模	8	训练/测试分割、训练、预测、评估、交叉验证、网格搜索
特征选择	4	方差过滤器、相关性过滤器、重要性排名
日期时间	4	提取零件、差异、过滤、设置索引
统计检验	6	t检验、方差分析、卡方检验、正态性、Mann-Whitney、Kruskal-Wallis
诠释	7	特征重要性、残差、混淆矩阵、ROC、学习曲线
聚类	5	K-Means、DBSCAN、肘部图、轮廓评分、聚类分析
尺寸	2	PCA，t-SNE
报告	2	Markdown报告，独立的HTML报告

所有102个工具都遵循相同的模式：接受DataFrame名称（或使用当前名称），执行操作，返回简洁的文本摘要（或用于可视化的PNG图像）。

特性

102数据科学工具 --从原始CSV到具有可解释性的训练模型的完整流程
状态数据存储 --命名的DataFrames、训练模型和绘图图像在工具调用中持续存在
13阶段代理工作流程 --内置指令指导LLM通过EDA→ 清洁→ 特征工程→ 建模→ 报告
决策框架 --何时使用参数测试与非参数测试，如何处理缺失数据，选择哪种编码
可视化为图像 --matplotlib图形转换为PNG并作为MCP图像对象返回
ML模型管理 --训练、评估、比较和调整scikit学习模型（线性/逻辑回归、随机森林、梯度增强、决策树）
统计测试 --t检验、方差分析、卡方检验、正态性、Mann-Whitney、Kruskal-Wallis与效应大小
聚类 --K-Means、DBSCAN、肘部法、轮廓分析、聚类分析
降维 --PCA（解释方差）和t-SNE（对大型数据集进行自动采样）
报告生成 --Markdown(.md +PNG绘图）或内嵌base64图像的自包含HTML
陷阱预防 --12个记录在案的常见错误警告代理（例如，分割前的目标编码=数据泄漏）

架构概述

┌─────────────────────────────────────────────────────┐
│              MCP Client (Claude, etc.)              │
│                                                     │
│   "Load sales.csv, show a quality report,           │
│    clean missing values, train a random forest"     │
└──────────────────────┬──────────────────────────────┘
                       │  stdio (JSON-RPC)
          ┌────────────┴────────────┐
          │   FastMCP Server        │
          │   (server.py)           │
          │                         │
          │   ┌───────────────┐     │
          │   │  DataStore    │     │
          │   │  · DataFrames │     │
          │   │  · ML Models  │     │
          │   │  · Plot cache │     │
          │   └───────────────┘     │
          │                         │
          │   15 tool modules       │
          │   (102 tools total)     │
          │                         │
          │   · pandas              │
          │   · scikit-learn        │
          │   · matplotlib/seaborn  │
          │   · category-encoders   │
          │   · scipy               │
          └─────────────────────────┘

无需外部服务 --所有计算都在进程中进行。服务器通过stdio（标准MCP传输）进行通信。

技术栈

图层	技术	详细信息
协议	MCP（FastMCP）	stdio传输，JSON-RPC
数据	pandas 2.0+，numpy 1.24+	DataFrame操作，数值计算
ML	scikit-learn 1.3+	回归、分类、聚类、预处理
可视化	matplotlib 3.7+，seaborn 0.13+	14种绘图类型，Agg后端→ PNG导出
编码	类别编码器2.6+	目标编码、频率编码
统计学	学科	t检验、方差分析、卡方检验、正态性检验、非参数检验
图片	枕头10+	MCP图像响应的PNG编码
构建	孵化器	PEP 517构建系统
在13个测试文件中测试	pytest 7+	200+个测试函数
格式	openpyxl（Excel）、pyarrow（Parquet）	其他文件格式的可选依赖项

项目结构

mcp-data-science/
├── pyproject.toml                       # Build config + dependencies
├── CLAUDE.md                            # Architecture reference
│
├── src/mcp_data_science/
│   ├── __init__.py                      # main() entry point → mcp.run(transport="stdio")
│   ├── __main__.py                      # python -m support
│   ├── server.py                        # FastMCP instance + registers all 15 tool modules
│   ├── state.py                         # DataStore: named DataFrames, ML models, plot cache
│   ├── instructions.md                  # 13-phase agent workflow guide (loaded as MCP instructions)
│   └── tools/
│       ├── _plot_helpers.py             # fig_to_image() — matplotlib Agg → PNG → MCP Image
│       ├── loading.py                   # 11 tools: load/save CSV/Excel/Parquet, merge, pivot, melt, concat
│       ├── inspection.py                # 9 tools: head, tail, info, stats, shape, quality_report, profile
│       ├── cleaning.py                  # 9 tools: duplicates, missing, filter, rename, clip, sort, bin
│       ├── transformation.py            # 9 tools: create_column, log, normalize, mapping, dtype, string_clean
│       ├── encoding.py                  # 4 tools: one-hot, target, label, frequency encoding
│       ├── visualization.py             # 14 tools: histogram, bar, scatter, box, violin, QQ, heatmap…
│       ├── analysis.py                  # 8 tools: correlation, outliers, group_aggregate, crosstab
│       ├── modeling.py                  # 8 tools: train/test split, train, predict, evaluate, grid_search
│       ├── feature_selection.py         # 4 tools: correlation_filter, variance_filter, importance
│       ├── datetime_tools.py            # 4 tools: extract_parts, diff, filter, set_index
│       ├── statistical_tests.py         # 6 tools: ttest, anova, chi_square, normality, mann_whitney, kruskal
│       ├── interpretation.py            # 7 tools: feature_importance, residuals, confusion_matrix, ROC, PR
│       ├── clustering.py                # 5 tools: kmeans, dbscan, elbow, silhouette, cluster_profile
│       ├── dimensionality.py            # 2 tools: pca_transform, tsne_plot
│       └── reporting.py                 # 2 tools: save_report (md), save_report_html
│
└── tests/
    ├── conftest.py                      # Fixtures: sample_df, numeric_df, datetime_df, classification_df
    ├── sample_data.csv                  # Test fixture data
    ├── test_server.py                   # Server bootstrap, tool count verification
    ├── test_state.py                    # DataStore management (25 tests)
    ├── test_loading.py                  # CSV/Excel/Parquet loading (18 tests)
    ├── test_inspection.py               # Inspection tools (15 tests)
    ├── test_cleaning.py                 # Cleaning tools (23 tests)
    ├── test_transformation.py           # Transformation tools (22 tests)
    ├── test_encoding.py                 # Encoding tools (9 tests)
    ├── test_visualization.py            # Visualization tools (26 tests)
    ├── test_analysis.py                 # Analysis tools (18 tests)
    ├── test_modeling.py                 # Modeling tools (14 tests)
    ├── test_feature_selection.py        # Feature selection tools (9 tests)
    ├── test_datetime_tools.py           # Datetime tools (11 tests)
    └── test_reporting.py                # Reporting tools (8 tests)

先决条件

需求	版本	安装
python	3.10+	python.org
紫外线（推荐）	最新	`pip install uv` 或 docs.astral.sh

备注：不需要GPU。所有计算都在CPU上运行。可选依赖关系(openpyxl 对于Excel， pyarrow 用于拼花地板）是自动安装的。

安装

快速设置（推荐）

git clone https://github.com/AstyanM/mcp-data-science.git
cd mcp-data-science
pip install -e .

具有测试依赖关系

pip install -e ".[test]"

使用紫外线

uv venv --python 3.13
uv pip install -e ".[test]"

用法

作为MCP服务器

添加到您的MCP客户端配置中（例如。， .mcp.json，克劳德桌面配置）：

{
  "mcpServers": {
    "mcp-data-science": {
      "command": "python",
      "args": ["-m", "mcp_data_science"]
    }
  }
}

服务器在stdio上启动，并将所有102个工具暴露给MCP客户端。

使用MCP Inspector（交互式测试）

mcp dev src/mcp_data_science/server.py

在以下位置打开web UI http://localhost:6274:

设置命令= python，论点= -m mcp_data_science，然后单击连接
去工具选项卡--列出了所有102个工具
呼叫 load_csv 首先使用CSV路径，然后调用任何其他工具

直接执行

python -m mcp_data_science

运行测试

pytest tests/

代理工作流

该服务器包括一个内置的13阶段工作流程指南，指导LLM如何系统地处理数据科学任务：

Phase 1:  Loading & First Look      →  load_csv, get_shape, get_head, get_info
Phase 2:  Exploratory Data Analysis  →  quality_report, get_statistics, plot_histogram, plot_bar
Phase 3:  Statistical Testing        →  normality_test, ttest, anova, chi_square
Phase 4:  Data Cleaning              →  drop_duplicates, fill_missing, string_clean, clip_outliers
Phase 5:  Feature Engineering        →  create_column, extract_datetime_parts, log_transform
Phase 6:  Categorical Encoding       →  one_hot_encode, target_encode, label_encode
Phase 7:  Feature Selection          →  variance_filter, correlation_filter, feature_importance
Phase 8:  Dimensionality Reduction   →  pca_transform, tsne_plot
Phase 9:  Normalization              →  normalize (only for distance-based models)
Phase 10: Modeling                   →  train_test_split, train_model, evaluate_model
Phase 11: Model Interpretation       →  plot_residuals, plot_confusion_matrix, plot_roc_curve
Phase 12: Clustering                 →  elbow_plot, kmeans_cluster, silhouette_score
Phase 13: Reporting                  →  save_report, save_report_html

决策框架

工作流程包括常见选择的决策树：

决策	框架
缺失数据	<5% → 填充中位数/众数·5–30%→ 调查·>50%→ 考虑放弃
组间比较试验	2组+正常→ t检验·2组+非正常→ 曼惠特尼·3+组→ 方差分析或Kruskal-Wallis
分类编码	2-10个独特→ 一个热门·>10个独特→ 目标编码·序号→ 标签编码
归一化	线性/逻辑模型→ 是·基于树的模型→ 没有

关键模式

工具注册：每个模块导出 register_tools(mcp, store)，被叫进来 server.py
状态: DataStore 持有 dict[str, pd.DataFrame] + dict[str, dict] 对于ML模型。所有工具均接受 df_name: str = "" （空=当前）
突变：工具通过以下方式修改存储中的DataFrame store.set(name, df) 并返回简洁的文本摘要
可视化：工具创建matplotlib图形，通过转换 fig_to_image() → Image(data=png_bytes, format="png")，总是 plt.close(fig) 之后
建模：模型存储为 {"model": sklearn_obj, "type": str, "features": list, "target": str} 在 DataStore._models
错误：工具返回可读的错误字符串，从不返回原始异常

支持的模型

任务	模型
回归	线性回归、随机森林、梯度提升、决策树
分类	逻辑回归、随机森林、梯度提升、决策树
聚类	K-Means，DBSCAN
降维	PCA、t-SNE

贡献

欢迎投稿！请先打开一个问题，讨论您想更改什么。

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

新工具规则

跟随 register_tools(mcp, store) 模式
永远不要打印到stdout——它是为MCP stdio协议保留的（使用 logging → stderr）
可视化工具必须始终关闭图形(plt.close(fig))防止内存泄漏
工具文档字符串面向LLM——保持清晰，并包含参数示例
create_column 用途 df.eval() （安全的pandas表达式），从不使用Python eval()

作者

马丁·阿斯蒂安 — GitHub

许可证

该项目根据MIT许可证获得许可——请参阅许可证文件以获取详细信息。