内容
# 智能Colab MCP桥接（实验性）
此仓库包含一个实验性设置，通过轻量级Flask服务器使用ngrok将Claude Desktop连接到Google Colab运行时。目标是在Colab（CPU/GPU）上实现受控、资源感知的远程Python代码执行，同时通过Claude Desktop本地编排任务。
**本仓库反映了原始构建的系统，而没有后续的加固或重构。**
---
## 📊 系统架构
```
┌────────────────┐ ┌───────────────────┐
│ Claude Desktop │ │ Google Colab │
│ （推理） │ │ （计算） │
└───────┬────────┘ └─────────┬─────────┘
│ │
JSON-RPC（标准输入/输出） Flask服务器
│ │
┌───────▼────────┐ ┌─────────▼─────────┐
│ 本地MCP代理│◄────────►│ ngrok隧道 │
│ （状态/配置） │ HTTP │ （公共URL） │
└────────────────┘ └───────────────────┘
```
**工作原理：**
1. **本地MCP代理：** 轻量级Python脚本通过Claude Desktop在您的PC上运行。处理超时、检查点和文件管理。
2. **远程执行器：** Colab笔记本通过ngrok隧道公开Flask API。
3. **桥梁：** Claude发送代码→本地代理→Colab执行→结果返回到Claude。
**重要：** Claude Desktop自动启动MCP服务器。 Colab笔记本必须手动启动以提供ngrok端点。
---
## ✨ 功能
- **远程执行：** 在Colab GPU/CPU上运行Pandas、PyTorch、Scikit-Learn
- **智能超时：**
- 快速模式（2分钟）：变量检查，轻量计算
- 长模式（10分钟）：模型训练，数据集下载
- **分段操作：** 将大型循环分成安全的批次以避免超时
- **本地持久性：**
- 长运行任务的可恢复检查点
- 从Colab `/content` 自动下载文件到本地机器
- **环境探测：** 查询RAM、GPU和安装的软件包在执行之前
- **内存管理：** 清理端点以释放RAM而无需重启运行时
---
## 📂 仓库结构
```
smart-colab-mcp/
├── agent/
│ └── mcp_smart_colab_v2.py # 本地MCP桥接（从环境变量读取）
├── colab/
│ └── smart_colab_executor.ipynb # Colab后端（Flask + ngrok）
├── config/
│ └── claude_desktop_config.example.json
├── requirements.txt
└── README.md
```
---
## 🚀 设置说明
### 阶段1：Colab设置
1. 在Google Colab中打开`colab/smart_colab_executor.ipynb`
2. **设置您的ngrok身份验证令牌：**
```python
!ngrok authtoken YOUR_TOKEN_HERE
```
在[ngrok.com/dashboard](https://dashboard.ngrok.com)获取免费令牌
3. 运行笔记本中的所有单元格
4. **复制打印的公共HTTPS URL** （例如，`https://xxxx-xx-xx.ngrok-free.app`)
5. **保持笔记本运行** - 关闭它会杀死服务器
### 阶段2：本地设置
```bash
git clone https://github.com/G-karthick0501/Smart-colab-MCP.git
cd Smart-colab-MCP
pip install -r requirements.txt
```
**所需包：**
- `mcp` - 模型上下文协议
- `requests` - HTTP客户端
- `flask` - Web框架（Colab侧）
- `pyngrok` - ngrok Python包装器（Colab侧）
### 阶段3：配置Claude Desktop
**位置：** `%APPDATA%\Claude\claude_desktop_config.json` （Windows）
**示例配置：**
```json
{
"mcpServers": {
"smart-colab": {
"command": "C:\\Path\\To\\Python.exe",
"args": ["C:\\Path\\To\\agent\\mcp_smart_colab_v2.py"],
"env": {
"COLAB_URL": "https://your-ngrok-url.ngrok-free.app",
"LOCAL_SAVE_DIR": "C:\\Path\\To\\results",
"CHECKPOINT_DIR": "C:\\Path\\To\\checkpoints"
}
}
}
}
```
**重要：**
- 在Windows路径中使用**双反斜杠** （`\\`）
- 用实际的ngrok URL替换`COLAB_URL`
- 在使用前创建`LOCAL_SAVE_DIR`和`CHECKPOINT_DIR`文件夹
- 编辑配置后重启Claude Desktop
---
## 🛠️ 可用工具
| 工具 | 描述 | 超时 |
|------|-------------|---------|
| `check_colab_connection` | 验证ngrok隧道是否活跃 | 10秒 |
| `probe_colab_environment` | 获取GPU/RAM/软件包信息 | 30秒 |
| `run_code_quick` | 执行短Python代码片段 | 2分钟 |
| `run_code_long` | 执行重任务（训练/下载） | 10分钟 |
| `run_chunked_operation` | 分批处理循环，支持恢复 | 5分钟/批次 |
| `list_colab_files` | 列出Colab `/content` 目录中的文件 | 30秒 |
| `download_from_colab` | 下载文件到 `LOCAL_SAVE_DIR` | 5分钟 |
| `cleanup_colab` | 释放RAM/GPU内存 | 30秒 |
| `list_colab_variables` | 显示运行时变量和形状 | 15秒 |
| `get_checkpoint` | 检索保存的检查点数据 | 立即 |
---
## 🔍 验证和故障排除
### 检查正在运行的进程
**Windows：**
```cmd
tasklist /fi "imagename eq python.exe"
```
**预期输出：**
```
Image Name PID Session Mem Usage
Claude.exe 1234 Console 450,000 K
python.exe 5678 Console 80,000 K ← Memory MCP（如果配置）
python.exe 9012 Console 60,000 K ← Colab MCP
```
### 测试Colab健康端点
```bash
curl https://your-ngrok-url/health
```
**预期响应：**
```json
{
"status": "ok",
"uptime_minutes": 15,
"memory_available_gb": 10.5,
"memory_used_pct": 15.2
}
```
### 常见问题
| 问题 | 原因 | 解决方案 |
|---------|-------|----------|
| `Connection refused` | Colab笔记本未运行 | 重新运行笔记本单元格 |
| `COLAB_URL not set` | 缺少环境变量 | 检查Claude Desktop配置 |
| ngrok URL更改 | 笔记本重启 | 更新配置为新URL |
| `404 Not Found` | 错误的端点路径 | 验证URL是否包含`/health` |
| 执行超时 | 代码执行时间>10分钟 | 使用`run_chunked_operation` |
| 内存错误 | Colab RAM已满 | 调用`cleanup_colab()` |
| 文件未找到 | 错误的Colab路径 | 检查`/content/`目录 |
---
## 🔒 安全考虑
### 已知风险（未加固）
- **任意代码执行：** `/execute` 端点运行任何Python代码而无需验证
- **无身份验证：** ngrok URL在笔记本运行时可公开访问
- **无沙箱：** 代码执行具有完整的Colab运行时权限
- **单线程：** 无执行锁定；并发请求可能冲突
- **公开暴露：** ngrok隧道如果URL泄露，可以被发现
### 推荐做法
**对于用户：**
1. 永远不要公开分享ngrok URL
2. 在执行前审查所有代码
3. 为Colab实验使用专用Google帐户
4. 立即终止会话
5. 监控Colab活动仪表板
**未实现（未来工作）：**
- 请求签名/ HMAC身份验证
- IP白名单
- 执行锁定（`threading.Lock`）
- 危险操作限制
- 速率限制
---
## 📋 已知限制
这些是**故意记录**并跟踪以供未来改进：
- **执行模型：** 同步，阻塞Flask工作线程
- **无并发控制：** 并行请求可能导致竞争条件
- **输出大小限制：** 非常大的输出可能超过传输限制
- **分段执行：** 假设简单的循环体；复杂的缩进可能会破坏
- **无持久性：** 会话状态在Colab运行时断开时丢失
- **会话生命周期：** 取决于Colab的空闲超时（~90分钟）
- **ngrok轮换：** URL每次会话都会更改（除非付费计划）
- **Flask主机绑定：** 应该使用`host="0.0.0.0"`以提高可靠性
---
## 🔮 未来工作
计划的改进（在GitHub问题中跟踪）：
**安全和身份验证：**
- [ ] 添加请求签名/ API密钥身份验证
- [ ] 实现IP白名单
- [ ] 限制危险的Python操作（`os.system`，`subprocess`等）
- [ ] 添加具有执行ID的结构化日志记录
**可靠性：**
- [ ] 添加执行锁定机制（`threading.Lock`）
- [ ] 实现作业队列以处理并发请求
- [ ] 提高分段执行的鲁棒性（处理复杂缩进）
- [ ] 添加`/shutdown`端点以进行干净的服务器终止
**功能：**
- [ ] 在外部持久化远程状态（Google Drive同步）
- [ ] 用自托管隧道（Tailscale，Cloudflare）替换ngrok
- [ ] 支持多个运行时（Kaggle，VM，本地Docker）
- [ ] 为长时间操作添加流式stdout
- [ ] 实现自动重新连接Colab断开
---
## 🔄 MCP通信工作原理
```
┌─────────────────┐
│ Claude Desktop │ 读取config.json
│ │ 将MCP服务器作为子进程启动
└────────┬────────┘
│
│ JSON-RPC通过标准输入/输出
│
┌────────▼────────┐
│ MCP服务器 │ Python进程在您的PC上
│ （mcp_smart_ │ 读取COLAB_URL从环境变量
│ colab_v2.py） │
└────────┬────────┘
│
│ HTTP POST/GET
│
┌────────▼────────┐
│ ngrok隧道 │ 公共HTTPS → Colab VM
└────────┬────────┘
│
┌────────▼────────┐
│ Flask服务器 │ 在Colab笔记本中运行
│ （Colab运行时） │ 通过exec（）执行Python
└─────────────────┘
```
**示例JSON-RPC消息：**
```json
// 来自Claude的请求
{
"jsonrpc": "2.0",
"method": "run_code_quick",
"params": {"code": "print(2 + 2)"},
"id": 1
}
// 来自MCP的响应
{
"jsonrpc": "2.0",
"result": {
"success": true,
"stdout": "4\n",
"execution_time_sec": 0.12
},
"id": 1
}
```
**关键点：**
- MCP服务器在Claude Desktop启动时**自动**启动
- Claude和MCP之间的通信是**本地**的（标准输入/输出）
- MCP和Colab之间的通信是**HTTP**的（通过ngrok）
- Colab笔记本必须**手动**启动并保持运行
---
## 📋 推荐的.gitignore
```
# Python
venv/
__pycache__/
*.pyc
*.pyo
# 本地存储
results/
checkpoints/
memory_db/
memory_backups/
# IDE
.vscode/
.idea/
*.swp
*.swo
# 机密
*.token
.env
```
---
## 🎯 状态和动机
**当前状态：**
- ✅ 实验性概念验证
- ✅ 单用户，本地使用仅
- ❌ 未针对安全进行加固
- ❌ 不适用于生产环境
**为什么存在：**
该项目旨在探索：
- 实用MCP编排模式
- 无需SSH复杂性的远程执行
- 管理Colab的瞬态运行时约束
- 使用检查点的长运行ML工作流
- 关注与计算（Colab）分离：推理（Claude）
**有什么不同：**
- **执行分类：** 明确的快速/长/分段模式
- **本地检查点：** 崩溃或断开后恢复
- **探测优先原则：** 执行前检查资源
- **故障隔离：** 正确的超时处理和错误表面
---
## 📚 其他资源
- [MCP协议规范](https://spec.modelcontextprotocol.io/)
- [Claude Desktop MCP指南](https://docs.anthropic.com/claude/docs/model-context-protocol)
- [FastMCP文档](https://github.com/jlowin/fastmcp)
- [ngrok文档](https://ngrok.com/docs)
- [Google Colab常见问题](https://research.google.com/colaboratory/faq.html)
---
## 🤝 贡献
通过问题和拉取请求欢迎贡献！
**提交前：**
- 删除个人路径和令牌
- 使用新的Colab会话进行测试
- 记录任何新端点或工具
- 如果架构更改，请更新此README
**好主意的问题：**
- 添加执行锁以防止并发运行
- 实现基本请求身份验证
- 改进错误消息和日志记录
- 为MCP工具添加单元测试
---
## ⚠️ 免责声明
此代码远程执行任意Python代码。 **不安全**用于多用户或公共部署。仅在受信任的环境中使用受信任的代码。
**用户负责：**
- 在执行前审查所有代码
- 管理ngrok URL隐私
- 了解执行权限
- 监控Colab使用情况和成本
**作者提供：**
- 教育示例代码
- 已知风险文档
- 无保证或担保
**自担风险。** 不建议用于生产环境。
---
## 🙏 致谢
- 灵感来自[doobidoo/mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)模式
- 使用[FastMCP](https://github.com/jlowin/fastmcp)、[Flask](https://flask.palletsprojects.com/)和[ngrok](https://ngrok.com)构建
- 感谢Anthropic团队提供MCP协议
---
## 📝 许可证
MIT许可证 - 免费使用，需注明出处
---
**维护者：** [G-karthick0501](https://github.com/G-karthick0501)
**仓库：** [github.com/G-karthick0501/Smart-colab-MCP](https://github.com/G-karthick0501/Smart-colab-MCP)
**最后更新：** 2026年1月
