MCP Docker执行服务器
一个模型上下文协议（MCP）服务器，提供安全的Docker容器执行和流支持。设计用于与Cursor和其他MCP兼容客户端无缝协作。
特性
- 灵活的执行模式
- 缓冲模式（默认）：命令完成时返回完整输出 - 流模式：长时间运行的命令的实时输出流 - TTY支持：可选伪TTY分配（默认关闭）
- 生产就绪安全
- 命令允许列表/拒绝列表策略 - 用户权限控制（默认情况下为非root） - 路径访问限制 - 速率限制 - 全面的审计日志记录
- 稳健的资源管理
- 用于任意大输出的内存安全流式传输 - 可配置的块大小和缓冲区限制 - 超时支持，优雅取消 - 并发执行限制
- 企业可观察性
- 结构化JSON日志记录 - 度量收集（延迟、吞吐量、错误） - 跟踪ID相关性 - 健康检查
快速开始
安装选项
1.从npm安装（推荐）
npm install -g mcp-docker-exec2.使用Docker镜像
docker pull ghcr.io/YOUR_USERNAME/mcp-docker-exec:latest3.从源代码安装
git clone https://github.com/YOUR_USERNAME/mcp-docker-exec.git
cd mcp-docker-exec
npm install
npm run build使用游标
添加到光标MCP设置(~/.cursor/mcp/settings.json):
对于npm安装：
{
"mcpServers": {
"docker-exec": {
"command": "mcp-docker-exec",
"args": [],
"env": {
"MCP_DOCKER_ALLOW_ROOT": "false",
"MCP_DOCKER_MAX_BYTES": "10485760"
}
}
}
}对于Docker安装：
{
"mcpServers": {
"docker-exec": {
"command": "docker",
"args": [
"run",
"--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock",
"ghcr.io/YOUR_USERNAME/mcp-docker-exec:latest"
],
"env": {
"MCP_DOCKER_ALLOW_ROOT": "false",
"MCP_DOCKER_MAX_BYTES": "10485760"
}
}
}
}可用工具
docker_exec
在正在运行的容器中执行命令。
{
"name": "docker_exec",
"arguments": {
"id": "container_name_or_id",
"cmd": ["sh", "-c", "ls -la"],
"stream": false,
"tty": false,
"user": "appuser",
"workdir": "/app",
"env": ["NODE_ENV=production"],
"timeoutMs": 30000,
"chunkBytes": 16384
}
}码头日志
使用以下选项检索容器日志。
{
"name": "docker_logs",
"arguments": {
"id": "container_name_or_id",
"tail": "100",
"follow": true,
"since": "2024-01-01T00:00:00Z",
"chunkBytes": 16384
}
}docker_ps
列出具有筛选选项的容器。
{
"name": "docker_ps",
"arguments": {
"all": true,
"name": "web"
}
}码头_检验
检查Docker对象（容器、映像、网络、卷）。
{
"name": "docker_inspect",
"arguments": {
"kind": "container",
"id": "container_name_or_id"
}
}健康
检查服务器健康状况和Docker连接。
{
"name": "health",
"arguments": {}
}配置
所有配置都是通过环境变量完成的：
Docker连接
DOCKER_HOST：Docker守护进程套接字/地址（默认：本地套接字）
资源限制
MCP_DOCKER_MAX_BYTES：缓冲模式下的最大输出大小（默认值：1048576）MCP_DOCKER_CHUNK_BYTES：流数据块大小（默认值：16384）MCP_DOCKER_MAX_CONCURRENT：最大并发执行数（默认值：10）MCP_DOCKER_TIMEOUT_MS：命令的默认超时（可选）
安全
MCP_DOCKER_SECURITY：启用安全功能（默认值：true）MCP_DOCKER_DEFAULT_USER：命令的默认用户（可选）MCP_DOCKER_ALLOW_ROOT：允许根执行（默认值：false）MCP_DOCKER_COMMAND_POLICY_MODE：“排外主义者”、“丹尼主义者”或“无”MCP_DOCKER_COMMAND_PATTERNS：逗号分隔的正则表达式模式MCP_DOCKER_DENIED_PATHS：逗号分隔的拒绝路径（默认：/proc、/sys、/dev）MCP_DOCKER_DENIED_FLAGS：逗号分隔的危险标志（默认值：--privileged，--pid=host，--net=host）
速率限制
MCP_DOCKER_RATE_LIMITS：启用速率限制（默认值：true）MCP_DOCKER_EXEC_PER_MINUTE：每分钟最多执行次数（默认值：60）MCP_DOCKER_LOGS_PER_MINUTE：每分钟最大日志请求数（默认值：30）
审计与可观察性
MCP_DOCKER_AUDIT：启用审核日志记录（默认值：true）MCP_DOCKER_AUDIT_FILE：审核日志文件路径（可选）MCP_DOCKER_AUDIT_RETENTION_DAYS：日志保留期（默认值：30）MCP_DOCKER_LOG_LEVEL：日志级别（调试/信息/警告/错误，默认值：信息）MCP_DOCKER_STRUCTURED_LOGS：使用JSON日志（默认值：true）
其他
MCP_DOCKER_DRY_RUN：仅记录，不执行（默认值：false）
安全考虑
⚠️ 警告：此服务器提供对Docker容器的访问，这相当于对主机系统的root访问。
最佳实践
- 永远不要暴露给不受信任的客户端：此服务器仅供本地开发使用。
- 默认情况下使用非root：设置默认非root用户：
MCP_DOCKER_DEFAULT_USER=nobody- 启用命令策略：限制可用命令：
MCP_DOCKER_COMMAND_POLICY_MODE=allowlist
MCP_DOCKER_COMMAND_PATTERNS="^ls,^cat,^grep,^echo"- 限制路径：阻止访问敏感目录：
MCP_DOCKER_DENIED_PATHS="/etc,/root,/var/lib"- 使用只读容器 如果可能的话。
- 启用审核日志记录 用于生产用途：
MCP_DOCKER_AUDIT_FILE=/var/log/mcp-docker-exec/audit.jsonl例子
基本命令执行
// List files in container
{
"name": "docker_exec",
"arguments": {
"id": "my-app",
"cmd": ["ls", "-la", "/app"]
}
}流式长时间运行命令
// Follow application logs
{
"name": "docker_exec",
"arguments": {
"id": "my-app",
"cmd": ["tail", "-f", "/var/log/app.log"],
"stream": true
}
}使用输入执行
// Send data to command
{
"name": "docker_exec",
"arguments": {
"id": "my-app",
"cmd": ["sh", "-c", "cat > /tmp/data.txt"],
"stdin": "Hello, World!"
}
}包含以下内容的容器日志
// Stream container logs
{
"name": "docker_logs",
"arguments": {
"id": "my-app",
"follow": true,
"tail": "50"
}
}远程Docker支持
连接到远程Docker守护进程：
# SSH connection (key-based auth only)
DOCKER_HOST=ssh://user@remote-host
# TCP connection (ensure TLS is configured)
DOCKER_HOST=tcp://remote-host:2376故障排除
指挥吊架
- 确保
tty: false（默认）用于非交互式命令 - 使用
stream: true对于长时间运行的命令 - 设置适当
timeoutMs
权限不足
- 检查
MCP_DOCKER_ALLOW_ROOT设置 - 验证用户是否存在于容器中
- 查看安全策略设置
速率限制错误
- 调整
MCP_DOCKER_EXEC_PER_MINUTE - 检查审计日志以了解使用模式
大产量问题
- 使用
stream: true用于具有大输出的命令 - 调整
MCP_DOCKER_CHUNK_BYTES网络性能 - 监视器
MCP_DOCKER_MAX_BYTES用于缓冲模式
发展
从源头构建
git clone https://github.com/your-org/mcp-docker-exec
cd mcp-docker-exec
npm install
npm run build运行测试
npm test # Unit tests
npm run test:integration # Integration tests建筑
mcp-docker-exec/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── docker/
│ │ ├── DockerManager.ts # Core Docker operations
│ │ ├── ExecSession.ts # Execution session handling
│ │ └── StreamDemuxer.ts # Stream demultiplexing
│ ├── security/
│ │ ├── SecurityManager.ts # Command & access policies
│ │ └── AuditLogger.ts # Audit trail
│ ├── observability/
│ │ ├── Logger.ts # Structured logging
│ │ └── MetricsCollector.ts # Metrics collection
│ └── config/
│ └── Config.ts # Configuration management
└── tests/
├── unit/ # Unit tests
└── integration/ # Integration tests许可证
MIT许可证-有关详细信息，请参阅许可证文件。
贡献
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
支持
- 问题：https://github.com/your-org/mcp-docker-exec/issues
- 文档：https://github.com/your-org/mcp-docker-exec/wiki
- 安全：security@your-org.com