e2b-MCP服务器
项目介绍
e2b-mcp
在E2B沙箱中安全地运行MCP (Model Context Protocol)服务器。
e2b-mcp提供了一种简单的方法，在隔离的云环境中执行MCP服务器，使不信任的工具和代码能够安全执行。无需直接在主机系统上运行MCP服务器，而是可以在具有自动资源管理和清理的E2B安全沙箱中运行它们。
使用场景
我们构建了e2b-mcp，以便Cased可以代表用户运行MCP服务器，并与我们的DevOps代理集成。但e2b-mcp有许多使用场景：
AI代理平台
- 安全工具执行：让AI代理使用文件操作、git命令和web API，而不影响您的基础设施
- 用户特定沙箱：使用每个用户的凭证和权限在隔离环境中运行MCP服务器
- 动态工具发现：按需发现并提供新功能给代理
SaaS应用程序
- 多租户工具执行：在专用沙箱中安全执行用户请求的操作（文件处理、数据分析）
- MCP API网关：作为REST端点暴露MCP工具，内置安全性和隔离性
- 无服务器MCP：根据需求扩展MCP服务器实例，无需管理基础设施
开发者工具及IDE
- 代码执行环境：为在线IDE和编码平台提供安全的代码执行环境
- 插件沙箱：安全运行不受信任的MCP插件，不影响主机环境
- CI/CD集成：在受控访问的隔离环境中执行构建/测试工具
企业解决方案
- 合规与安全：通过隔离所有工具执行来满足安全要求
- 客户入门：让客户在部署前安全地尝试工具和集成
- 托管AI服务：向客户提供AI能力，而不会暴露后端系统
特性
- 安全执行：在隔离的E2B沙箱中运行MCP服务器
- CLI & API：命令行界面和Python API
- 工具发现：自动从MCP服务器发现工具
- 异步/同步支持：异步和同步执行模式
- 自动清理：自动沙箱和资源管理
- 包管理：自动安装MCP服务器依赖项
- 多语言：通过CLI或构建特定语言的包装器，从任何语言使用
安装
uv pip install e2b-mcp
先决条件
- E2B API密钥：从e2b.dev获取免费的API密钥
- 环境变量：设置环境中的
E2B_API_KEY
export E2B_API_KEY="your_api_key_here"
快速开始
CLI用法
# 添加一个GitHub MCP服务器
e2b-mcp server add github \
--command "npx -y @modelcontextprotocol/server-github" \
--env GITHUB_PERSONAL_ACCESS_TOKEN=your_token
# 发现可用工具
e2b-mcp tools list github
# 执行一个工具
e2b-mcp tools execute github search_repositories \
--params '{"query": "python", "per_page": 5}'
# 快速一次性执行（不保存配置）
e2b-mcp quick "npx -y @modelcontextprotocol/server-filesystem /tmp" \
list_directory --param path=/tmp
Python API
import asyncio
from e2b_mcp import E2BMCPRunner, ServerConfig
async def main():
# 创建运行器
runner = E2BMCPRunner()
# 添加MCP服务器
runner.add_server(ServerConfig(
name="filesystem",
command="npx -y @modelcontextprotocol/server-filesystem /tmp",
description="文件系统操作"
))
# 发现工具
tools = await runner.discover_tools("filesystem")
print(f"发现 {len(tools)} 个工具")
# 执行一个工具
result = await runner.execute_tool(
"filesystem",
"write_file",
{"path": "/tmp/example.txt", "content": "Hello World!"}
)
print(result)
# 运行异步代码
asyncio.run(main())
📖 CLI文档
服务器管理
# 添加新的MCP服务器配置
e2b-mcp server add <name> --command "<command>" [选项]
# 列出所有已配置的服务器
e2b-mcp server list [--json]
# 移除服务器配置
e2b-mcp server remove <name> [--yes]
添加服务器选项：
--command：运行MCP服务器的命令（必需）--env KEY=VALUE：环境变量（可多次使用）--package：要安装的Python包--description：服务器描述--timeout：超时时间（分钟，默认：10）
工具操作
# 列出已配置服务器的工具
e2b-mcp tools list <server_name> [--json]
# 执行一个工具
e2b-mcp tools execute <server_name> <tool_name> [选项]
执行工具选项：
--params：工具参数作为JSON字符串--param key=value：单个参数（可多次使用）--json：输出原始JSON响应
快速执行
# 不保存服务器配置的情况下执行
e2b-mcp quick "<command>" <tool_name> [选项]
快速执行选项：
--params：工具参数作为JSON字符串--param key=value：单个参数--env KEY=VALUE：环境变量--json：输出原始JSON响应
配置
# 显示当前配置
e2b-mcp config [--show]
# 编辑配置文件
e2b-mcp config --edit
# 重置所有配置
e2b-mcp config --reset
CLI示例
# GitHub集成
export GITHUB_TOKEN="your_token"
e2b-mcp server add github \
--command "npx -y @modelcontextprotocol/server-github" \
--env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN
e2b-mcp tools execute github search_repositories \
--params '{"query": "e2b", "per_page": 3}'
# 文件系统操作
e2b-mcp server add fs \
--command "npx -y @modelcontextprotocol/server-filesystem /tmp"
e2b-mcp tools execute fs write_file \
--param path=/tmp/test.txt \
--param content="Hello CLI!"
e2b-mcp tools execute fs read_file \
--param path=/tmp/test.txt
# 使用快速执行进行一次性操作
e2b-mcp quick "npx -y @modelcontextprotocol/server-filesystem /tmp" \
list_directory --param path=/tmp --json
配置存储在~/.e2b-mcp/servers.json中，并可在不同环境中共享。
配置
服务器配置
from e2b_mcp import ServerConfig
# 方法1：使用ServerConfig类
config = ServerConfig(
name="my_server",
command="python -m my_mcp_server --stdio",
package="my-mcp-server-package", # 可选
description="我的自定义MCP服务器",
timeout_minutes=10,
env={"DEBUG": "1"} # 可选环境变量
)
runner.add_server(config)
# 方法2：使用字典
runner.add_server_from_dict("my_server", {
"command": "python -m my_mcp_server --stdio",
"package": "my-mcp-server-package",
"description": "我的自定义MCP服务器",
"timeout_minutes": 10,
"env": {"DEBUG": "1"}
})
配置参数
- name：MCP服务器的唯一标识符
- command：启动MCP服务器的命令
- package：要安装的Python包（可选）
- description：人类可读的描述
- timeout_minutes：沙箱超时时间（默认：10分钟）
- env：环境变量（可选）
API参考
E2BMCPRunner
用于在E2B沙箱中管理MCP服务器的主要类。
方法
__init__(api_key: Optional[str] = None)
使用E2B API密钥初始化运行器。
add_server(config: ServerConfig) -> None
添加MCP服务器配置。
add_server_from_dict(name: str, config_data: Dict[str, Any]) -> None
从字典添加MCP服务器配置。
list_servers() -> List[str]
列出所有已配置的服务器名称。
async discover_tools(server_name: str) -> List[Tool]
从MCP服务器发现工具。
async execute_tool(server_name: str, tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]
在MCP服务器上执行一个工具。
execute_tool_sync(server_name: str, tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]
execute_tool的同步封装。
async create_session(server_name: str) -> AsyncContextManager[Session]
创建一个管理的MCP会话（高级用法）。
示例
基本工具执行
import asyncio
from e2b_mcp import E2BMCPRunner
async def main():
runner = E2BMCPRunner()
# 添加一个简单的测试服务器
runner.add_server_from_dict("test", {
"command": "python /tmp/test_mcp_server.py",
"description": "带有基本工具的测试服务器"
})
# 执行工具
time_result = await runner.execute_tool("test", "get_time", {"format": "iso"})
echo_result = await runner.execute_tool("test", "echo", {"text": "Hello!"})
print(f"时间: {time_result}")
print(f"回声: {echo_result}")
asyncio.run(main())
同步使用
from e2b_mcp import E2BMCPRunner
runner = E2BMCPRunner()
runner.add_server_from_dict("test", {
"command": "python /tmp/test_mcp_server.py"
})
# 同步执行
result = runner.execute_tool_sync("test", "get_time", {"format": "readable"})
print(result)
会话管理（高级）
async def advanced_usage():
runner = E2BMCPRunner()
runner.add_server_from_dict("filesystem", {
"command": "python -m mcp_server_filesystem --stdio",
"package": "mcp-server-filesystem"
})
# 手动管理会话生命周期
async with runner.create_session("filesystem") as session:
print(f"会话ID: {session.session_id}")
print(f"沙箱ID: {session.sandbox_id}")
# 退出上下文时会话自动清理
支持的MCP服务器
e2b-mcp与支持标准MCP协议的任何MCP服务器兼容。一些流行的服务器包括：
- mcp-server-filesystem：文件系统操作
- mcp-server-git：Git仓库管理
- mcp-server-sqlite：SQLite数据库操作
- mcp-server-brave-search：网络搜索功能
- mcp-server-slack：Slack集成
安全性
e2b-mcp提供了多个安全层：
- 沙箱隔离：所有MCP服务器都在隔离的E2B沙箱中运行
- 网络隔离：沙箱具有受控的网络访问
- 资源限制：自动CPU、内存和时间限制
- 自动清理：使用后自动销毁沙箱
- 无主机访问：MCP服务器无法访问本地文件系统
错误处理
from e2b_mcp import E2BMCPRunner, MCPError
try:
runner = E2BMCPRunner()
result = await runner.execute_tool("不存在的", "工具", {})
except MCPError as e:
print(f"MCP操作失败: {e}")
except ValueError as e:
print(f"配置错误: {e}")
开发
本地开发
# 克隆仓库
git clone https://github.com/cased/e2b-mcp.git
cd e2b-mcp
# 以开发模式安装
pip install -e ".[dev]"
# 使用提供的脚本自动格式化和检查代码
./scripts/format
# 或手动运行各个工具
black .
ruff check .
开发脚本
项目在scripts/目录中包含了一些有用的开发脚本：
格式化脚本 (./scripts/format)
自动格式化和检查代码库：
- 运行
black进行代码格式化 - 运行
ruff check --fix --unsafe-fixes进行检查和自动修复 - 运行
ruff format进行导入排序 - 运行
mypy进行类型检查
./scripts/format
发布脚本 (./scripts/release)
处理完整的专业发布过程，包括全面的预飞行检查：
- 版本验证：确保提供的版本与
pyproject.toml匹配 - 预飞行检查：验证git状态、分支和所需工具
- 环境验证：检查PyPI凭据和依赖项
- 构建与发布：自动构建包并发布到PyPI
- Git标签：创建并推送git标签到GitHub
- GitHub发布：可选地创建带有自动生成说明的GitHub发布
发布前提条件：
# 1. 设置PyPI凭据（必需）
export TWINE_USERNAME=__token__
export TWINE_PASSWORD='your-pypi-api-token'
# 2. 安装所需工具
pip install build twine
# 3. 可选：安装GitHub CLI以创建发布
brew install gh # 或适用于您系统的等效命令
发布流程：
# 1. 手动更新pyproject.toml中的版本
# version = "0.2.0"
# 2. 提交版本更改
git add pyproject.toml
git commit -m "升级版本至0.2.0"
# 3. 使用相同的版本运行发布脚本
./scripts/release 0.2.0
发布脚本做了什么：
- ✅ 验证版本是否与
pyproject.toml匹配 - ✅ 检查干净的git状态和正确的分支
- ✅ 验证PyPI凭据和所需工具
- ✅ 使用
python -m build构建包 - ✅ 使用
twine upload发布到PyPI - ✅ 创建并推送git标签（
v0.2.0） - ✅ 可选地创建带有自动生成说明的GitHub发布
- ✅ 处理虚拟环境的去激活和重新激活以实现干净构建
安全特性：
- 在破坏性操作之前有多次确认提示
- 在开始之前验证所有前提条件
- 清晰的错误处理，附带帮助信息
- 安全的虚拟环境处理
测试
该包包括单元测试和集成测试：
单元测试
运行不需要E2B API访问的快速单元测试：
# 仅运行单元测试（快速）
pytest tests/test_basic.py
# 使用详细输出运行
pytest tests/test_basic.py -v
集成测试
运行创建真实E2B沙箱的综合集成测试：
# 设置E2B API密钥（集成测试需要）
export E2B_API_KEY="your_api_key"
# 运行集成测试
pytest tests/test_integration.py -v
# 运行所有测试，包括集成测试
pytest -v
测试命令
# 仅运行单元测试（不需要E2B API密钥）
pytest -m "not integration"
# 仅运行集成测试（需要E2B API密钥）
pytest -m integration
# 运行所有测试
pytest
# 运行覆盖率测试
pytest --cov=e2b_mcp
# 运行特定测试
pytest tests/test_integration.py::TestE2BMCPIntegration::test_tool_discovery -v
集成测试类别
- 基础功能：会话创建、工具发现、工具执行
- 包安装：测试具有pip依赖项的MCP服务器
- 环境变量：测试自定义环境配置
- 错误处理：测试故障场景和清理
- 性能：并发会话和快速创建/销毁
- 压力测试：同时进行多项操作
注意：集成测试创建真实的E2B沙箱，可能需要几分钟才能完成。它们需要有效的E2B API密钥。
运行示例
# 设置E2B API密钥
export E2B_API_KEY="your_api_key"
# 运行基本示例
python examples/basic_usage.py
贡献
欢迎贡献！请随时提交Pull Request。
许可证
MIT许可证 - 详情见LICENSE文件。
相关项目
- MCP (Model Context Protocol) - 本库实现的协议
- E2B - 用于AI的安全云沙箱
- MCP服务器 - 官方MCP服务器实现