AI导哈

数据分析服务器

一个基于自然语言请求进行数据分析、预处理和可视化的MCP服务器，适用于大型语言模型（LLMs）。

  • by chaeminyoon
  • Python
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 chaeminyoon/python-mcp-data_analysis

使用说明

English | 한국어

数据分析MCP

来自单个自然语言请求的数据分析、预处理和可视化——用于LLM的MCP数据分析服务器

快速开始 · 演示 · 使用场景 · 案例研究 · 图表主题 · 刀具清单 · LLM集成指南

一览
60 专业工具·11个领域模块 5 可访问性验证图表主题 2 法学硕士后端（克劳德·OpenAI）
58 测试· 4-方式CI矩阵 0-依赖性调色板验证器 ~4.2K LOC(src/)

一句话总结 --一个MCP服务器，通过分析一直接收CSV和自然语言请求→ 预处理→ 可视化→ 模型诊断。 LLM只决定调用哪个工具；服务器拥有每一个计算和每一个可访问性保证。 pytest强制执行色觉缺陷和对比度检查，因此服务器返回 经验证的图表，而不仅仅是漂亮的——这是核心区别。

特性

  • 自动可视化 --任何CSV中的提要：自动检测列角色（数字/分类/日期时间/ID…），推荐合适的图表并说明原因，并当场呈现(recommend_visualizations → plot_auto)
  • 图表主题系统 --5个主题： modern （默认）， dark, minimal, vibrant, classic对话中的一句话——“切换到黑暗”——重新设计了接下来的每张图表(set_chart_style)
  • 经过计算验证的调色板 --每个主题都通过了四次可访问性检查（OKLCH亮度带·色度底·3种色觉缺陷模拟下相邻对间距ΔE≥12·与背景的对比度为3:1）， 由pytest执行验证器是纯Python(palette_check.py)并在每次提交时在CI中运行
  • 立即查看结果 --图表在对话中以MCP图像的形式内联显示(view_chart)，CLI会自动打开操作系统查看器和实时web结果库(data-analysis-viewer)实时监控输出
  • 60种专业工具 --分析、预处理（缺失值/异常值/编码/缩放）、特征工程、静态和交互式可视化、组合和比较图、分布和数据质量诊断、假设检验、模型比较/评估/调整/诊断
  • 韩国第一 --支持韩文列名和轴标签，内置韩文响应系统提示
  • 对任何数据都安全 --空文件、所有NaN列、单类目标、高基数类别：边缘输入返回为明显错误而不是崩溃，因此LLM可以自行恢复

演示--分析→ 过程→ 可视化

这是实际的使用流程。用户用自然语言提问，LLM选择并调用MCP工具， 下面的每个数字和图表都是服务器实际返回的未经编辑的结果。

1.分析 --了解数据。

You: analyze house_price.csv
AI:  545 rows x 12 columns. 34 outliers (6.2%) detected in the price column.
     [calls get_dataset_info, detect_outliers]

2.流程 --去除异常值，并在一张图像中比较前后。

You: remove the outliers and show me a before/after comparison
AI:  Removed 34 rows. (545, 12) → (511, 12)
     Here is the comparison chart — the tail above 1.3M on the left is gone on the right.
     [calls remove_outliers → plot_before_after → view_chart, chart displayed inline]

plot_before_after 从磁盘中提取原始版本，从缓存中提取处理后的版本 在同一轴上并排放置，这样你就可以在一张图像中看到预处理发生了什么变化。

3.可视化 --对清理后的数据进行自动推荐并绘制出来。

You: recommend the best visualization and draw it
AI:  The area-price correlation is the strongest at |r|=0.80 (0.33 before removal → 0.80 after).
     Generated a scatter plot, colored by bedrooms.
     [calls recommend_visualizations → plot_auto → view_chart, chart displayed inline]

预处理改变了可视化——仅去除异常值就提高了相关性 从0.33到0.80，图表直接显示了这一点。完整的MCP请求/响应JSON 本次对话的内容 docs/LLM_INTEGRATION.md.

图表主题

每个图表工具都会绘制活动主题。您可以在对话中切换 (set_chart_style)或者将其设置为服务器启动 MCP_CHART_THEME 环境变量。

深色 极简 鲜艳
主题 用途
modern （默认） 平静的专业调色板、浅色网格、左对齐的标题
dark 专门为深色表面重新计算的调色板——仪表板、对话
minimal 静音，最小网格——报告、论文
vibrant 高色度、强对比度——强调展示
classic matplotlib/plotly默认样式（遗留兼容性，未验证可访问性）

每个调色板，除了 classic 在以下条件下，相邻槽之间保持ΔE≥25 色觉缺陷模拟（protan/deutan/tritan），每种颜色的对比度均为3:1 主题本身的背景。插槽 秩序本身就是一种安全机制 --它是由 穷举搜索以最大化最小相邻对ΔE，从而任意重新排序序列 颜色会使测试失败。当调色板需要8种以上的颜色时，答案不是 更多颜色，但可折叠成“其他”(fold_other)或小倍数 (plot_small_multiples).故意没有双轴（两个y轴）工具。

使用场景

60种工具闪闪发光 工作流，而不是孤立的电话。四种常见的流程， 使用工具链，LLM实际上在每一步都会调用。

1.在10分钟内理解一个不熟悉的数据集

"Can I trust this CSV? Walk me through it, structure to quality"

profile_dataset → plot_missingness （缺失是随机的还是结构性的？）→ find_duplicates → recommend_visualizations → 渲染顶部 plot_auto 挑选。 使命诊断是第一位的，因为 未知质量数据的图表是 似是而非的谎言超过5%的缺失，自动推荐列表会增加缺失 自行诊断。

Real run — NDBC buoy data: per-column missing rates on the left; the matrix on the right reveals the wave-height sensor's gaps are time-block structured, not random.

2.构建报告和演示材料

"Make it minimal for a report, and summarize the top revenue drivers as a Pareto"

set_chart_style("minimal") → plot_pareto （有多少项目占80%？）→ plot_stacked_bar(normalize=True) （成分比较）→ stat_tile （英雄号码卡）→ 将生成的PNG直接放入文档中。对于幻灯片，单个 set_chart_style("dark") 用深色表面调色板重新渲染相同的图表——每个 主题通过了CVD和对比度检查，因此 会议室里的投影仪和 色觉缺陷的同事都得到了相同的信息.

Real run — KMST accident-type Pareto in the minimal theme: muted tones + a single % axis, 80% crossover annotated, ready to paste into a report.

3.模型开发循环

"Build a churn model and tell me whether I should collect more data"

compare_models （基线）→ tune_hyperparameters → plot_learning_curve （如果验证曲线仍在攀升，那么更多的数据就是答案）→ plot_roc_pr （不平衡，公关告诉真相）→ plot_calibration （前提条件 基于阈值的决策）→ 对于回归， plot_residuals （结构缺陷R²看不见）。 你最终得到的不是一个单一的准确数字，而是 一套证据 “为什么这个模型值得信赖”.

Real run — predicting wave height from buoy data: the 0.63 gap between train and validation curves says "right now it is memorizing noise".

4.用一张图表回答一个商业问题

问题 唯一能回答它的工具
“哪些渠道贡献了80%的收入？” plot_pareto
“为什么总产量比上个季度下降了？” plot_waterfall （按项目贡献细分）
“按地区×产品的平均单价？” plot_pivot_heatmap
“去年与今年相比，每个分支机构都发生了什么变化？” plot_slope
“本月只有一个关键指标” stat_tile （当答案是一个数字时，不绘制图表是正确的选择）
Real run — "201 total months of suspensions: where did they come from?" — one waterfall: collisions (+52) and casualties (+47) are half of it.

每个输出都可以 在对话中内联显示 与单一 view_chart 呼叫-- 它返回MCP ImageContent（base64 PNG），因此像Claude Desktop/Code这样的多模式客户端会显示 无需打开文件即可立即得到结果（通过实际的stdio协议进行验证）。

案例研究——6章海事数据

工具如何在两个真实数据集上链接成一个分析故事： 这个 美国国家海洋和大气管理局NDBC 46042浮标 （蒙特利湾，2023年的47137次观测——自动下载 根据脚本）和 139 KMST（韩国海上安全法庭）判决 （捆绑）。每 下图是未经编辑的工具输出，通过一次运行复制 examples/maritime_case_study.py，每章都有注释 哪种设计规则介入以及为什么介入.

第1章·趋势——平滑不得隐藏数据

"Show me last year's wave-height trend. Clean up the noise but don't erase the raw data"

plot_rolling --所有12585个原始观测值都保留在背景中（静音灰色），仅 7天移动平均线为原色。1月至3月的风暴季节是一种趋势 而单个风暴尖峰永远不会消失。 设计规则：强调一种颜色， 为上下文而静音——颜色是层次结构。

第二章关系——过去一万点，散点图

plot_hexbin --与散点图相同的数据会折叠成一个斑点。编码密度 作为 顺序斜坡 （一种色调，浅色→dark）揭示了结构：波高方差 随着风力的增强而增长。 设计规则：用亮度编码连续量 一种色调，而不是多种色调。

第3章·分布——测试统计和视觉诊断是一组

test_normality （夏皮罗p≈0，不正常）+ plot_qq --测试只说“不是”； Q-Q图显示 如何 它不是：在参考线上方逃逸的右端是 沉重的右尾——极端的波浪高度。对于设计载荷计算，该尾部为 整个要点。

第4章可预测性——两条曲线，而不是一个准确度数字

plot_learning_curve --根据风速、阵风、波浪周期和 压力给出了验证R²0.34，泛化差距为0.63。两条曲线 诊断它：“这些功能还不够，现在它正在记忆噪音。” 设计规则：不确定性（±1σ）作为光填充带，两个系列总是得到一个图例。

第5章·优先级和贡献——询问事故数据的两个问题

plot_pareto --前5种类型（伤亡、碰撞、火灾/爆炸、接地、接触） 占判决的80%。酒吧（个人股）和累计线共享a 单%轴 --没有双轴。 plot_waterfall --分解201个月 按类型分列：碰撞（+52）和伤亡（+47）各占一半。 设计规则：在每个条上直接贴标签；+/-取调色板颜色1和2。

第6章·当答案是一个数字时

stat_tile --“去年最大波高是多少？”的答案是数字 8.18米，不是图表。 设计规则：不画不需要画的东西也是 可视化决策。

# Full reproduction (buoy data auto-downloads once, ~4MB)
python examples/maritime_case_study.py

快速开始

git clone https://github.com/chaeminyoon/Data-Analyze-MCP.git
cd Data-Analyze-MCP
pip install -e .                        # installs server + client + viewer
python generate_all_test_data.py        # generate 3 demo datasets (optional)

克劳德桌面/克劳德代码

claude_desktop_config.json 或 .mcp.json:

{
  "mcpServers": {
    "data-analysis": {
      "command": "data-analysis"
    }
  }
}

然后和克劳德谈谈： “分析house_price.csv，删除异常值，然后将其可视化” --图表出现在对话中。

OpenAI API（捆绑客户端）

export OPENAI_API_KEY=sk-... MODEL_NAME=gpt-4o-mini
python data_client.py

在每个回合结束时，新的图表会在操作系统默认查看器中自动打开 （禁用 AUTO_OPEN_RESULTS=0).

实时结果库

data-analysis-viewer            # http://127.0.0.1:8400

在分析旁边保持打开状态，生成的输出每3秒刷新一次。 PNG渲染为网格；交互式Plotly HTML在新选项卡中打开。没有额外的依赖关系。

MCP服务器工具（共60个）

Exploration & Profiling (4) — understand the data
工具 说明
get_dataset_info 基本数据集信息（形状、数据类型、缺失值）
profile_dataset 综合分析（统计、相关性、分布）
detect_data_types 自动列角色分类（数字/分类/日期时间/ID/文本）
find_duplicates 检测并计数重复行
Preprocessing (5) — clean
工具 说明
handle_missing_values 缺失值处理（平均值、中位数、众数、下降值、ffill）
detect_outliers 异常检测（IQR、Z评分）
remove_outliers 异常值移除（全部检测到）
encode_categorical 分类编码（标签，一次性）
scale_features 缩放比例（标准、最小、最大）
Feature Engineering (3) — create features
工具 说明
create_derived_feature 基于公式的导出列(df.eval)
create_polynomial_features 多项式和交互特征
extract_datetime_features 日期时间特征（年、月、星期几等）
Auto Visualization (2) — automatic recommendation & rendering
工具 说明
recommend_visualizations 自动分析数据→ 合理的图表推荐+可执行工具call
plot_auto 自动选择并呈现1-3列（或无列）的图表(interactive 支持）

数字的→直方图·分类→bar·数字×数字→分散·数字×分类（≤8级）→箱线图· 数字×分类（9-16级）→小倍数·日期时间×数字→直线·分类×分类→交叉表· +分类→色调/分组。推荐列表自动包含时间×构成→面积图， 当缺失值超过5%时，进行缺失诊断。

Chart Style (2) — design themes
工具 说明
list_chart_styles 可用主题和当前主题
set_chart_style 切换每个后续图表的设计（现代/黑暗/极简/活力/经典）
Visualization (15) — static PNG + interactive HTML
工具 说明
plot_histogram / plot_boxplot / plot_scatter 可定制的基本图表
plot_before_after 在共享轴上并排预处理之前/之后（直方图/箱线图）
plot_line 时间序列线（分组、重采样、采样）， interactive)
plot_rolling 原始系列（静音）+移动平均线（主要）——内部噪声趋势
plot_bar 分类频率/聚合条（top_n， interactive)
plot_correlation_heatmap 相关热图（发散斜坡）
plot_pivot_heatmap 类别×类别×数字汇总热图——不是“多少”，而是“多少”
plot_hexbin 密度hexbin——数万个点涂抹散点图时的替代品
analyze_target_distribution 目标分布+不平衡检测
plot_interactive_scatter/histogram/boxplot/heatmap 绘图HTML（缩放和悬停）
Composition & Comparison (6)
工具 说明
plot_stacked_bar 堆叠的棒材（100%标准化，9级以上的“其他”折叠，分段间隙）
plot_area 堆叠面积——总面积和随时间变化的组成（支持重新采样）
plot_slope 斜率图——每个项目在两个时间点之间的变化，两端直接标记
plot_small_multiples 小倍数——共享轴上每个类别的迷你图表（拆分而不是颜色循环）
plot_pareto Pareto——有多少项构成80%，单轴（无双轴）
plot_waterfall 瀑布——每个项目对总变化的贡献（+/-颜色，直接标签）
Distribution & Data Quality (5) — distribution & quality diagnostics
工具 说明
plot_ecdf 经验CDF——读取直方图隐藏的确切百分位数
plot_violin 小提琴——暴露箱图隐藏的双峰形状（内置四分位数）
plot_missingness 2-面板缺失诊断——每列速率+行序矩阵（结构间隙）
plot_qq Q-Q图——视觉伴侣 test_normality （斜尾和重尾诊断）
stat_tile 英雄数字图块——当答案是一个数字时，使用的卡片而不是图表
Machine Learning (8) — modeling & diagnostics
工具 说明
compare_models RandomForest/XGBoost/逻辑回归/线性比较
evaluate_model 混淆矩阵、特征重要性、详细指标
tune_hyperparameters GridSearchCV/随机化搜索CV
plot_roc_pr ROC+PR曲线并排（避免了不平衡数据上的ROC错觉，多类OvR）
plot_calibration 校准曲线——概率是真实的吗？（阈值决策的前提条件）
plot_feature_importance 重要性/
plot_residuals 残差与预测值+残差分布——结构缺陷R²看不见
Statistical Analysis (6) — hypothesis testing
工具 说明
calculate_correlation 皮尔森/斯皮尔曼/肯德尔
test_normality Shapiro-Wilk正态性检验
test_ttest / test_anova 组均值比较
test_chi_square 类别独立性测试
calculate_confidence_interval 平均值的置信区间
Data & Results Management (4) — cache & outputs
工具 说明
list_cached_datasets / clear_cache 内存数据集缓存管理
view_chart 在对话中内联显示图表（MCP图像内容）
list_outputs 列出生成的输出（最新的优先）

建筑学

graph LR
    classDef blue fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef purple fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef orange fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef green fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef gray fill:#fafafa,stroke:#333,stroke-width:2px

    User((User))
    subgraph Client [Client Layer]
        Agent[Claude or<br/>LangGraph Agent]
    end
    LLM[LLM Engine<br/>Claude / OpenAI]
    subgraph MCPLayer [MCP Server]
        Server[FastMCP<br/>60 Tools]
        Theme[Chart<br/>Themes]
        Cache[Dataset<br/>Cache]
    end
    Files[(CSV · PNG · HTML)]
    Viewer[Results Gallery<br/>:8400]

    User <-->|natural language| Agent
    Agent <-->|prompt/response| LLM
    Agent <-->|MCP tools/call| Server
    Server <--> Cache
    Server <--> Theme
    Server <-->|read/write| Files
    Files -->|live refresh| Viewer
    Viewer --> User

    class User gray
    class Agent blue
    class LLM orange
    class Server,Cache,Theme purple
    class Files,Viewer green

分工：LLM只决定 使用哪个工具调用哪个参数；每一个实际 计算（panda/sklearn/matplotlib）在服务器上运行。无效输入返回为 isError 有一个明确的信息，所以LLM会自我纠正。

工程亮点

这 设计决策 在功能列表后面。每个项目不是“建造了什么”，而是“为什么这样决定”。

  • 可访问性降低到计算 --“这个颜色漂亮吗”是主观的，但“色觉缺陷的同事能把这两个系列区分开吗”是可计算的。 palette_check.py 实现sRGB→OKLab（Ottosson）、CIELAB（D65）、Machado 2009 CVD矩阵和WCAG相对亮度 直接来自已发布的公式，无外部依赖每个调色板必须通过的四个检查（亮度带、色度底、相邻对CVDΔE、3:1背景对比度）由pytest在每次提交时强制执行。
  • 调色板顺序本身就是一种安全机制 --系列颜色是按照插槽顺序分配的，该顺序不是任意的：它是由 穷举搜索以最大化最小相邻对CVD距离 (theming.py).随意重新排序颜色会破坏可访问性测试——错误不会悄无声息地通过。
  • 从结构上阻止了“添加更多颜色”的诱惑 --当需要8种以上的颜色时，解决方案是折叠成“其他”(fold_other)或小倍数(plot_small_multiples)没有更多的颜色。有 故意不使用双轴（两个y轴）工具 --甚至帕累托也绘制在一个百分比轴上。如果该工具不存在，则不会出现坏图表。
  • 自动可视化是一个规则引擎 — recommend_visualizations 对列角色进行分类（数字/分类/日期时间/ID），根据确定性规则选择图表，并返回 **可执行 tool_call**数据的形状决定了图表，而不是LLM的直觉。当缺失值超过5%时，会自动在建议中插入缺失诊断。
  • 边缘输入上的恢复而不是崩溃 --空文件、所有NaN列、单类目标、高基数类别：这些都不会杀死服务器。他们回来了 isError +这是一个明确的信息，以便LLM选择自己的下一个工具。专用边缘机箱套件(test_edge_cases.py)防止倒退。
  • 可选依赖关系的优雅降级 --没有 xgboost, compare_models 继续使用其余型号，只有在明确请求XGBoost时才会出现明显错误(ml.py).安装环境永远不会停止服务器。
  • 通过三种途径暴露的结果 --MCP ImageContent （base64 PNG）内联用于多模式客户端，CLI自动打开操作系统查看器，以及3秒滚动的网络库(:8400).无论客户是谁，用户都会立即看到结果。

质量·检测

显示这一点的部分是 维护代码，而不是投资组合代码。

  • 4路CI矩阵 python 3.11/3.12 ×熊猫 2.2/3.0 横向奔跑(ci.yml).pandas 2和3的字符串数据类型不同(object 对 str)，因此两者都必须保持绿色，以捕捉字符串处理回归。
  • 58次测试·绒毛 --涵盖可视化、预处理、ML/统计、自动推荐、调色板、边缘案例和服务器/结果。无头渲染也通过以下方式进行验证 MPLBACKEND=Agg.
  • 可访问性作为CI门 --上述四个调色板检查是测试套件的一部分，因此涉及颜色的提交在未通过的情况下无法合并。
  • 基于公关的发展 --特征以分支形式着陆→PR→合并(feat/chart-themes, feat/tests-ci-license, …).历史一次读一个特征。
  • 可复制的人工制品 --本自述中的每个演示和案例研究图像都是 未经编辑的工具输出 来自 scripts/generate_demo_images.py 和 examples/maritime_case_study.py。没有手绘模型。
pip install -e ".[dev]"
ruff check src tests
pytest -q

项目结构

Expand 
Data-Analyze-MCP/
├── src/data_analysis/          # MCP server package (python -m data_analysis)
│   ├── server.py               #   shared FastMCP instance + theme initialization
│   ├── theming.py              #   chart theme system (5 presets + sequential/diverging ramps)
│   ├── palette_check.py        #   palette accessibility validator (OKLCH·CVD·WCAG, zero deps)
│   ├── viewer.py               #   results gallery web UI (:8400)
│   ├── config.py               #   environment-variable configuration
│   ├── cache.py / helpers.py   #   dataset cache · shared helpers · mark specs
│   ├── fonts.py / prompts.py   #   Korean fonts · system prompts
│   └── tools/                  #   60 tools by domain
│       ├── exploration.py         ├── preprocessing.py
│       ├── feature_engineering.py ├── visualization.py
│       ├── composition.py         ├── distribution.py
│       ├── auto_viz.py            ├── style.py
│       ├── results.py             ├── ml.py
│       └── statistics.py
├── data_client.py              # LangGraph conversational client (OpenAI)
├── examples/demo_session.py    # LLM-MCP session replay script
├── examples/maritime_case_study.py  # reproduces the 6-chapter maritime case study (auto-downloads NDBC)
├── docs/LLM_INTEGRATION.md     # integration guide with captured real I/O
├── scripts/generate_demo_images.py  # regenerates README demo images (unedited tool output)
├── generate_all_test_data.py   # generator for the 3 demo datasets
└── pyproject.toml              # src-layout package (pip install -e .)

配置

环境变量 默认值 描述
MCP_CHART_THEME modern 创业时的图表主题（现代/黑暗/极简/充满活力/经典）
MCP_OUTPUT_DIR outputs/ 保存图表和导出的位置
MODEL_NAME gpt-4o-mini 捆绑客户端的型号ID
AUTO_OPEN_RESULTS 1 从CLI自动打开结果（0=关闭）
MCP_CLASSIFICATION_MAX_UNIQUE 10 分类/回归决策阈值

文档

  • LLM集成指南 --Claude/OpenAI设置+捕获的4轮会话的完整MCP JSON
  • 会话重放 -准确地重新运行记录的I/O，不需要API密钥
  • 海事案例研究 --再现了6章案例研究的所有图表（真实的NDBC和KMST数据）
Python 3.11+ · FastMCP · pandas / scikit-learn / matplotlib / seaborn / plotly · 3 demo datasets included

相关 MCP