Content
# IPython 数据分析 MCP 服务器 / IPython Data Analysis MCP Server
[🇨🇳 中文](#中文版本) | [🇺🇸 English](#english-version)
---
## 中文版本
基于真正 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 运行：
```bash
# 安装 uvx（如果还没有安装）
pip install uvx
# 直接运行 MCP 服务器
uvx --from git+https://github.com/Hillyess/dataHill.git DATA_MCP.py
```
#### 方法二：本地安装开发
```bash
# 1. 克隆项目
git clone git@github.com: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）**：
```json
{
"mcpServers": {
"dataHill": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Hillyess/dataHill.git",
"DATA_MCP.py"
]
}
}
}
```
**本地开发配置**（如果使用方法二）：
```json
{
"mcpServers": {
"dataHill": {
"command": "python",
"args": ["/path/to/your/DATA_MCP.py"],
"env": {
"PYTHONPATH": "/path/to/your/project"
}
}
}
}
```
### 📖 使用指南
#### 基本工作流程
```python
# 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+ （取决于数据规模）
- **操作系统**: Windows/macOS/Linux
- **MCP 客户端**: Claude Desktop 或其他支持 stdio 的 MCP 客户端
### 📦 依赖项
#### 核心依赖
- `fastmcp>=0.5.0` - MCP 服务器框架
- `ipython>=8.0.0` - IPython 交互式环境
- `pandas>=2.0.0` - 数据处理和分析
- `numpy>=1.24.0` - 数值计算基础库
#### 数据支持
- `openpyxl>=3.1.0` - Excel .xlsx 文件支持
- `xlrd>=2.0.0` - Excel .xls 文件支持
#### 系统监控
- `psutil>=5.9.0` - 内存和系统监控
### 🤝 贡献指南
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
### 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
### 🙋♂️ 支持与反馈
- **问题报告**: [GitHub Issues](https://github.com/Hillyess/dataHill/issues)
- **功能请求**: [GitHub Discussions](https://github.com/Hillyess/dataHill/discussions)
---
## English Version
A lightweight data analysis MCP (Model Context Protocol) tool based on real IPython kernel, providing complete interactive Python data analysis environment with session management, data loading, real-time data viewing and other core functions.
### 🚀 Core Features
- **Real IPython Environment**: Based on IPython InteractiveShell, supports all IPython features
- **Multi-Session Management**: Independent session spaces, variable isolation, persistent state
- **Intelligent Data Loading**: Supports CSV/Excel/JSON, automatic encoding detection, smart variable naming
- **Real-time Monitoring**: Memory usage monitoring, variable management, execution history tracking
- **Complete Feature Support**: Python code, IPython magic commands, system command execution
- **Smart Sampling**: Large dataset friendly column data viewing, avoiding context overflow
### 📋 Feature List
#### 17 Core Tool Functions
1. **Session Management**
- `create_ipython_session` - Create new IPython session
- `list_ipython_sessions` - List all active sessions
- `get_session_status` - Get detailed session status
- `delete_ipython_session` - Delete specified session
2. **Code Execution**
- `execute_code` - Execute Python code, magic commands, system commands
- `get_execution_history` - Get execution history
3. **Data Loading**
- `load_csv_file` - Load CSV files (automatic encoding detection)
- `load_excel_file` - Load Excel files (supports .xlsx/.xls)
- `load_json_file` - Load JSON files
4. **Data Operations & Viewing**
- `list_dataframes` - List all DataFrames in session
- `get_dataframe_info` - Get detailed DataFrame information
- `preview_dataframe` - Preview DataFrame data
- `get_dataframe_summary` - Get statistical summary
- `sample_column_data` - Smart sampling for column data viewing
5. **Memory & Variable Management**
- `check_memory_usage` - Check memory usage
- `get_variable_info` - Get detailed variable information
- `clear_variables` - Clear variables to free memory
### 🛠️ Installation & Configuration
#### Method 1: Direct Run with uvx (Recommended)
No need to clone the project, run directly from GitHub using uvx:
```bash
# Install uvx (if not already installed)
pip install uvx
# Run MCP server directly
uvx --from git+https://github.com/Hillyess/dataHill.git DATA_MCP.py
```
#### Method 2: Local Installation for Development
```bash
# 1. Clone project
git clone git@github.com:Hillyess/dataHill.git
cd dataHill
# 2. Create virtual environment
conda create -n data-analyzer python=3.10
conda activate data-analyzer
# 3. Install dependencies
pip install -r requirements.txt
# 4. Test installation
python DATA_MCP.py
```
##### Configure MCP Client
##### Claude Desktop Configuration
Edit Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Recommended Configuration (using uvx)**:
```json
{
"mcpServers": {
"dataHill": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Hillyess/dataHill.git",
"DATA_MCP.py"
]
}
}
}
```
**Local Development Configuration** (if using Method 2):
```json
{
"mcpServers": {
"dataHill": {
"command": "python",
"args": ["/path/to/your/DATA_MCP.py"],
"env": {
"PYTHONPATH": "/path/to/your/project"
}
}
}
}
```
### 📖 Usage Guide
#### Basic Workflow
```python
# 1. Create session
create_ipython_session()
# Returns: {"success": true, "session_id": "session_a1b2c3d4", ...}
# 2. Load data
load_csv_file("data.csv", "session_a1b2c3d4", "df")
# 3. View data information
get_dataframe_info("df", "session_a1b2c3d4")
# 4. Smart sampling for data viewing
sample_column_data("df", "column_name", "session_a1b2c3d4", method="mixed", sample_size=20)
# 5. Execute analysis
execute_code("df.describe()", "session_a1b2c3d4")
# 6. Memory monitoring
check_memory_usage("session_a1b2c3d4")
# 7. Clean up session
delete_ipython_session("session_a1b2c3d4")
```
### 🔧 System Requirements
- **Python**: 3.8+
- **Memory**: Recommended 4GB+ (depends on data scale)
- **Operating System**: Windows/macOS/Linux
- **MCP Client**: Claude Desktop or other stdio-supported MCP clients
### 📦 Dependencies
#### Core Dependencies
- `fastmcp>=0.5.0` - MCP server framework
- `ipython>=8.0.0` - IPython interactive environment
- `pandas>=2.0.0` - Data processing and analysis
- `numpy>=1.24.0` - Numerical computation foundation
#### Data Support
- `openpyxl>=3.1.0` - Excel .xlsx file support
- `xlrd>=2.0.0` - Excel .xls file support
#### System Monitoring
- `psutil>=5.9.0` - Memory and system monitoring
### 🤝 Contributing
1. Fork this project
2. Create feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Open Pull Request
### 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
### 🙋♂️ Support & Feedback
- **Issue Reports**: [GitHub Issues](https://github.com/Hillyess/dataHill/issues)
- **Feature Requests**: [GitHub Discussions](https://github.com/Hillyess/dataHill/discussions)
---
⭐ If this project helps you, please give us a Star!
