MCP Data Science

MCP数据科学

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

______________________________________________________________________

动机

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

所有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-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)

______________________________________________________________________

先决条件

备注：不需要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:

1. 设置命令= python，论点= -m mcp_data_science，然后单击 连接
2. 去 工具 选项卡--列出了所有102个工具
3. 呼叫 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

决策框架

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

______________________________________________________________________

关键模式

• 工具注册：每个模块导出 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
• 错误：工具返回可读的错误字符串，从不返回原始异常

______________________________________________________________________

支持的模型

______________________________________________________________________

贡献

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

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

新工具规则

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

______________________________________________________________________

作者

• 马丁·阿斯蒂安 —

______________________________________________________________________

许可证

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