MCP Docker Exec

MCP Docker执行服务器

 ](https://www.npmjs.com/package/mcp-docker-exec) ](https://github.com/YOUR_USERNAME/mcp-docker-exec/pkgs/container/mcp-docker-exec)  

一个模型上下文协议（MCP）服务器，提供安全的Docker容器执行和流支持。设计用于与Cursor和其他MCP兼容客户端无缝协作。

特性

• 灵活的执行模式

- 缓冲模式（默认）：命令完成时返回完整输出 - 流模式：长时间运行的命令的实时输出流 - TTY支持：可选伪TTY分配（默认关闭）

• 生产就绪安全

- 命令允许列表/拒绝列表策略 - 用户权限控制（默认情况下为非root） - 路径访问限制 - 速率限制 - 全面的审计日志记录

• 稳健的资源管理

- 用于任意大输出的内存安全流式传输 - 可配置的块大小和缓冲区限制 - 超时支持，优雅取消 - 并发执行限制

• 企业可观察性

- 结构化JSON日志记录 - 度量收集（延迟、吞吐量、错误） - 跟踪ID相关性 - 健康检查

快速开始

安装选项

1.从npm安装（推荐）

npm install -g mcp-docker-exec

2.使用Docker镜像

docker pull ghcr.io/YOUR_USERNAME/mcp-docker-exec:latest

3.从源代码安装

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访问。

最佳实践

1. 永远不要暴露给不受信任的客户端：此服务器仅供本地开发使用。

1. 默认情况下使用非root：设置默认非root用户：

   MCP_DOCKER_DEFAULT_USER=nobody

1. 启用命令策略：限制可用命令：

   MCP_DOCKER_COMMAND_POLICY_MODE=allowlist
   MCP_DOCKER_COMMAND_PATTERNS="^ls,^cat,^grep,^echo"

1. 限制路径：阻止访问敏感目录：

   MCP_DOCKER_DENIED_PATHS="/etc,/root,/var/lib"

1. 使用只读容器 如果可能的话。

1. 启用审核日志记录 用于生产用途：

   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许可证-有关详细信息，请参阅许可证文件。

贡献

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

支持

• 问题：https://github.com/your-org/mcp-docker-exec/issues
• 文档：https://github.com/your-org/mcp-docker-exec/wiki
• 安全：security@your-org.com