🇨🇳 中文 |🇺🇸 英語

---

中文版本

基于真正 IPython 内核的轻量级数据分析 MCP (Model Context Protocol) 工具,提供完全な交互式 Python 数据分析环境,支持会话管理、数据加载、实时数据查看等核心功能。

🚀 核心特性

• 真正的 IPython 环境: 基于 IPython InteractiveShell,支持所有 IPython 功能
• 多会话管理: 独立的会话空间，变量隔离，持久化状态
• 智能数据加载: 支持 CSV / Excel/JSON,自动编码检测,智能变量命名
• 实时监控: 内存使用监控、变量管理、执行历史追踪
• 完整功能支持: Python代码、IPython魔法命令、系统命令执行
• 智能采样: 大数据集友好的列数据查看，避免上下文溢出

📋 功能清单

17个核心工具函数

1. 会话管理

• create_ipython_session - 创建新的 IPython 会话
• list_ipython_sessions - 列出所有活跃会话
• get_session_status - 获取会话详细状态
• delete_ipython_session - 削除指定会话

2. 代码执行

• execute_code - 执行 Python 代码、魔法命令、システム命令
• get_execution_history - 获取执行历史记录

3. 数据加载

• load_csv_file - 加载 CSV 文件(自动编码检测)
• load_excel_file - 加载 Excel 文件(支持 .xlsx/.xls)
• load_json_file - 加载 JSON 文件

4. 数据操作与查看

• list_dataframes - 列出会话中所有 DataFrame
• get_dataframe_info - 取得 DataFrame 详细信息
• preview_dataframe - 预览 DataFrame 数据
• get_dataframe_summary - 获取统计摘要
• sample_column_data - 智能采样查看列数据

5. 内存与变量管理

• check_memory_usage - 检查内存使用情况
• get_variable_info - 获取変数詳細
• clear_variables - 清理变量释放内存

🛠️ 安装配置

IPython 数据分析 MCP 服务器 / IPython Data Analysis MCP Server

🇨🇳 中文 | 🇺🇸 English

---

中文版本

基于真正 IPython 内核的轻量级数据分析 MCP (Model Context Protocol) 工具，提供完整的交互式 Python 数据分析环境，支持会话管理、数据加载、实时数据查看等核心功能。

🚀 核心特性

• 真正的 IPython 环境: 基于 IPython InteractiveShell，支持所有 IPython 功能
• 多会话管理: 独立的会话空间，变量隔离，持久化状态
• 智能数据加载: 支持 CSV/Excel/JSON，自动编码检测，智能变量命名
• 实时监控: 内存使用监控、变量管理、执行历史追踪
• 完整功能支持: Python代码、IPython魔法命令、系统命令执行
• 智能采样: 大数据集友好的列数据查看，避免上下文溢出

📋 功能清单

17个核心工具函数

1. 会话管理

   • create_ipython_session - 创建新的 IPython 会话
   • list_ipython_sessions - 列出所有活跃会话
   • get_session_status - 获取会话详细状态
   • delete_ipython_session - 删除指定会话

2. 代码执行

   • execute_code - 执行 Python 代码、魔法命令、系统命令
   • get_execution_history - 获取执行历史记录

3. 数据加载

   • load_csv_file - 加载 CSV 文件（自动编码检测）
   • load_excel_file - 加载 Excel 文件（支持 .xlsx/.xls）
   • load_json_file - 加载 JSON 文件

4. 数据操作与查看

   • list_dataframes - 列出会话中所有 DataFrame
   • get_dataframe_info - 获取 DataFrame 详细信息
   • preview_dataframe - 预览 DataFrame 数据
   • get_dataframe_summary - 获取统计摘要
   • sample_column_data - 智能采样查看列数据

5. 内存与变量管理

   • check_memory_usage - 检查内存使用情况
   • get_variable_info - 获取变量详细信息
   • clear_variables - 清理变量释放内存

🛠️ 安装配置

方法一：使用 uvx 直接运行（推荐）

无需克隆项目，直接使用 uvx 从 GitHub 运行：

# 安装 uvx（如果还没有安装）
pip install uvx

# 直接运行 MCP 服务器
uvx --from git+https://github.com/Hillyess/dataHill.git DATA_MCP.py

方法二：本地安装开发

# 1. 克隆项目
git clone [email protected]:Hillyess/dataHill.git
cd dataHill

# 2. 创建虚拟环境
conda create -n data-analyzer python=3.10
conda activate data-analyzer

# 3. 安装依赖
pip install -r requirements.txt

# 4. 测试安装
python DATA_MCP.py

配置 MCP 客户端

Claude Desktop 配置

编辑 Claude Desktop 配置文件：

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

推荐配置（使用 uvx）：

{
  "mcpServers": {
    "dataHill": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Hillyess/dataHill.git",
        "DATA_MCP.py"
      ]
    }
  }
}

本地开发配置（如果使用方法二）：

{
  "mcpServers": {
    "dataHill": {
      "command": "python",
      "args": ["/path/to/your/DATA_MCP.py"],
      "env": {
        "PYTHONPATH": "/path/to/your/project"
      }
    }
  }
}

📖 使用指南

基本工作流程

# 1. 创建会话
create_ipython_session()
# 返回: {"success": true, "session_id": "session_a1b2c3d4", ...}

# 2. 加载数据
load_csv_file("data.csv", "session_a1b2c3d4", "df")

# 3. 查看数据信息
get_dataframe_info("df", "session_a1b2c3d4")

# 4. 智能采样查看数据
sample_column_data("df", "column_name", "session_a1b2c3d4", method="mixed", sample_size=20)

# 5. 执行分析
execute_code("df.describe()", "session_a1b2c3d4")

# 6. 内存监控
check_memory_usage("session_a1b2c3d4")

# 7. 清理会话
delete_ipython_session("session_a1b2c3d4")

🔧 系统要求

• Python: 3.8+
• 内存: 建议 4GB+ （取决于数据规模）