Docker Bash MCP

Docker Bash MCP服务器

一个模型上下文协议（MCP）服务器，通过隔离的Docker容器提供安全的bash命令执行。使Claude Desktop能够在本地文件系统上运行bash命令，并具有可配置的卷挂载和自动清理功能。

  ](https://www.docker.com/) 

概述

此MCP服务器通过以下方式解决了让AI助手安全、受控地访问本地文件系统的挑战：

• 在中运行bash命令 隔离的Docker容器
• 安装 仅限您指定的目录
• 提供a 清洁的环境 对于每个命令
• 自动销毁 执行后的容器

特性

✅ 安全隔离 -每个命令都在新的Alpine Linux容器中运行\ ✅ 可配置访问 -仅装载您希望访问的目录\ ✅ 零坚持 -执行后容器被销毁\ ✅ 包管理 -按需安装Alpine软件包 apk\ ✅ 错误处理 -正确的错误代码、stderr捕获和超时支持\ ✅ 交叉平台的 -使用WSL在Linux、macOS和Windows上工作

先决条件

1. 码头工人 -

- 确保Docker守护进程正在运行 - 通过以下方式进行验证： docker ps

1. Python 3.10+

- 检查版本： python3 --version

1. Claude桌面版 - 点击此处下载

快速开始

# 1. Clone the repository
git clone https://github.com/scottwviteri/docker-bash-mcp.git
cd docker-bash-mcp

# 2. Run the setup script
chmod +x setup_docker_bash.sh docker_bash_mcp.py
./setup_docker_bash.sh

# 3. Restart Claude Desktop

# 4. Test it!
# In Claude Desktop, ask: "List available volume mounts"

配置

卷装载

编辑 docker_bash_mcp.py 自定义可访问的目录：

VOLUME_MOUNTS = {
    "/path/on/your/host": "/workspace/mount_name",
    "/another/path": "/workspace/another",
    # Add more as needed
}

示例:

VOLUME_MOUNTS = {
    "/home/user/projects": "/workspace/projects",
    "/home/user/documents": "/workspace/documents",
}

其他设置

DEFAULT_WORKING_DIR = "/workspace"  # Starting directory in container
DEFAULT_IMAGE = "alpine:latest"      # Docker image (lightweight Alpine Linux)
COMMAND_TIMEOUT = 120                # Seconds before command times out
CHARACTER_LIMIT = 25000              # Max output size

Claude桌面配置

安装脚本会自动更新您的配置，但您可以手动编辑：

位置:

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

内容:

{
  "mcpServers": {
    "docker-bash": {
      "command": "python3",
      "args": [
        "/absolute/path/to/docker_bash_mcp.py"
      ]
    }
  }
}

使用虚拟环境？ 使用venv Python的完整路径：

{
  "mcpServers": {
    "docker-bash": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/docker_bash_mcp.py"]
    }
  }
}

可用工具

1.execute_bash_docker

在Docker容器中执行bash命令。

参数:

• command （必需）：要执行的Bash命令
• working_directory （可选）：容器内的工作目录
• timeout （可选）：命令超时时间（秒）（默认值：120）

示例:

# List files
{"command": "ls -la /workspace"}

# Search for patterns
{"command": "grep -r 'TODO' /workspace"}

# Complex pipeline
{"command": "find /workspace -name '*.py' | wc -l"}

# Install and use tools
{"command": "apk add jq && cat data.json | jq '.field'"}

# Custom working directory
{
    "command": "pwd && ls",
    "working_directory": "/workspace/projects"
}

响应:

{
  "success": true,
  "stdout": "command output",
  "stderr": "",
  "returncode": 0,
  "working_directory": "/workspace",
  "docker_image": "alpine:latest"
}

2.列表计数

显示所有可用的卷装载。

参数:

• response_format （可选）： "json" （默认）或 "raw"

响应:

{
  "total_mounts": 2,
  "default_working_directory": "/workspace",
  "docker_image": "alpine:latest",
  "mounts": [
    {
      "host_path": "/home/user/projects",
      "container_path": "/workspace/projects",
      "exists": true,
      "readable": true,
      "writable": true
    }
  ]
}

3.安装包

测试是否可以安装Alpine软件包。

参数:

• package_name （必填）：Alpine包裹名称

备注：由于容器是短暂的，因此必须按照命令安装包：

apk add curl && curl https://example.com

使用示例

文件操作

User: What Python files are in my projects directory?
Claude: [uses execute_bash_docker with find command]

代码分析

User: Count total lines of Python code
Claude: [uses: find /workspace -name '*.py' -exec wc -l {} \; | awk '{sum+=$1} END {print sum}']

内容搜索

User: Find all TODOs in my codebase
Claude: [uses: grep -r 'TODO' /workspace]

数据处理

User: Extract all email addresses from text files
Claude: [uses: grep -rE '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' /workspace]

测试您的服务器

使用MCP检查器

官方MCP检查员为测试提供了一个可视化界面：

npx @modelcontextprotocol/inspector python3 docker_bash_mcp.py

这将在以下位置打开web UI http://localhost:6274 您可以在哪里：

• 查看可用工具
• 交互式测试命令
• 查看请求/响应消息
• 调试问题

命令行测试

# List available tools
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 docker_bash_mcp.py | jq

# Test a command
echo '{"jsonrpc":"2.0","method":"tools/call","id":2,"params":{"name":"execute_bash_docker","arguments":{"command":"ls -la /workspace"}}}' | python3 docker_bash_mcp.py | jq

建筑

┌─────────────────────┐
│  Claude Desktop     │
└──────────┬──────────┘
           │ MCP Protocol (stdio)
┌──────────▼──────────┐
│  docker_bash_mcp.py │
│   (FastMCP Server)  │
└──────────┬──────────┘
           │ Docker API
┌──────────▼──────────┐
│ Alpine Container    │
│  (Fresh per cmd)    │
│                     │
│  Mounted Volumes:   │
│  /workspace/...     │
└─────────────────────┘
           │
           ▼
    Your Local Filesystem

安全考虑

此服务器可以访问什么

✅ 仅在中明确列出的目录 VOLUME_MOUNTS\ ✅ 对已挂载目录的完全读/写访问权限\ ✅ 网络接入（集装箱可以接入互联网）

此服务器无法访问的内容

❌ 目录不在 VOLUME_MOUNTS\ ❌ 装载外部的系统文件\ ❌ 其他Docker容器\ ❌ 主机系统进程

最佳实践

1. 最小特权原则 -仅装载必要的目录
2. 使用只读挂载 -对于敏感数据，请考虑 :ro 旗帜
3. 查看命令 -在批准之前检查Claude建议的命令
4. 监督活动 -使用 docker ps 查看活动容器
5. 检查日志 -查看Claude Desktop日志中的异常活动

使支架只读

编辑 _build_docker_command() 在 docker_bash_mcp.py:

# Change from:
cmd.extend(["-v", f"{expanded_host}:{container_path}:rw"])

# To:
cmd.extend(["-v", f"{expanded_host}:{container_path}:ro"])

局限性

包装持久性

每个命令都必须重新安装软件包 因为容器是短暂的。

变通方案：使用预安装的软件包创建自定义Docker镜像：

FROM alpine:latest
RUN apk add --no-cache bash curl jq python3 git nodejs

然后更新 docker_bash_mcp.py:

DEFAULT_IMAGE = "your-custom-alpine"

Git操作

作品: ✅

• 本地git操作(init, status, add, commit, log, diff)
• 克隆公共存储库

不起作用: ❌

• 推送到远程存储库（无SSH密钥）
• 克隆私有存储库（无凭据）

为什么：容器无法访问：

• 你的 ~/.ssh/ 钥匙
• 你的 ~/.gitconfig
• 您的SSH代理

变通方案：装载SSH密钥（安全风险！）：

VOLUME_MOUNTS = {
    "/home/user/.ssh": "/root/.ssh",
    # ... other mounts
}

其他限制

• 无状态持久性：每个命令都重新开始
• Alpine/BusyBox：工具版本有限（例如，grep没有 --include)
• 演出：每个命令1-2秒的容器启动开销
• 文件所有权：容器以root身份运行；创建的文件可能具有不同的所有权

故障排除

Docker不可用

# Check Docker installation
docker --version

# Check if Docker is running
docker ps

# Start Docker (macOS)
open -a Docker

权限不足

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

服务器未连接

1. 检查克劳德桌面日志：

   # macOS/Linux
   tail -f ~/Library/Logs/Claude/mcp-docker-bash.log

   # Linux
   tail -f ~/.config/Claude/logs/mcp-docker-bash.log

1. 验证配置文件语法：

   python3 -m json.tool ~/.config/Claude/claude_desktop_config.json

1. 手动测试服务器：

   echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 docker_bash_mcp.py

支架不工作

# Check host paths exist
ls -la /path/to/mount

# Test mount manually with Docker
docker run --rm \
  -v /path/to/mount:/workspace/test:rw \
  alpine:latest \
  ls -la /workspace/test

命令超时

在命令中或全局增加超时时间：

# In docker_bash_mcp.py
COMMAND_TIMEOUT = 300  # 5 minutes

# Or per command
{"command": "long-task", "timeout": 300}

高级用法

自定义Docker镜像

对于常用软件包：

# Dockerfile
FROM alpine:latest
RUN apk add --no-cache \
    bash curl jq git \
    python3 py3-pip \
    nodejs npm

# Build
docker build -t my-mcp-alpine .

更新 docker_bash_mcp.py:

DEFAULT_IMAGE = "my-mcp-alpine"

多个挂载点

VOLUME_MOUNTS = {
    "/home/user/projects": "/workspace/projects",
    "/home/user/documents": "/workspace/docs",
    "/mnt/data": "/workspace/data",
    "/home/user/scripts": "/workspace/scripts",
}

环境变量

将环境变量传递给容器：

# In _build_docker_command():
cmd.extend(["-e", "MY_VAR=value"])
cmd.extend(["-e", f"HOME={os.environ.get('HOME')}"])

主机网络访问

要访问主机上运行的服务，请执行以下操作：

# In _build_docker_command():
cmd.extend(["--network", "host"])

⚠️ 安全警告：这为容器提供了对主机的完全网络访问权限。

性能提示

1. 预构建图像：使用预装软件包的自定义映像
2. 批处理命令：在一个命令中组合多个操作
3. 使用本机工具: grep/awk 对于简单任务，比Python脚本更快
4. 极限输出：使用 head, tail，或过滤器以减小输出大小
5. 避免重新安装：如果重复使用包，请创建自定义映像

Alpine Linux软件包

常见实用软件包：

文本处理: jq, yq, xmlstarlet\ 发展: git, python3, nodejs, go\ 网络: curl, wget, netcat-openbsd\ 构建工具: build-base, gcc, make

搜索套餐: https://pkgs.alpinelinux.org/packages

在命令中安装:

apk add package-name && your-command

贡献

欢迎投稿！请随时提交拉取请求。

开发环境设置

git clone https://github.com/scottwviteri/docker-bash-mcp.git
cd docker-bash-mcp

# Install dependencies
pip install "mcp[cli]" pydantic

# Run tests
python3 -m pytest tests/  # (if tests exist)

# Test with Inspector
npx @modelcontextprotocol/inspector python3 docker_bash_mcp.py

常见问题解答

Q： 容器在命令之间是否持久？\ A： 不，每个命令都在一个执行后被销毁的新容器中运行。

Q： 除了Claude Desktop之外，我还可以将其与其他MCP客户端一起使用吗？\ A： 是的！任何支持stdio传输的MCP兼容客户端都可以使用此服务器。

Q： Windows支持怎么样？\ A： Windows可与Docker Desktop和WSL配合使用。相应地调整配置中的路径。

Q： 我可以在容器中使用GPU吗？\ A： 是，添加 --gpus all 转到docker命令（需要nvidia docker）。

Q： 如何查看Claude正在运行的命令？\ A： 检查Claude Desktop日志或在检查器中启用调试模式。

Q： 这个可以安全使用吗？\ A： 是的，配置得当。仅装载您信任Claude可以访问的目录，并在批准前查看命令。

版本历史

• 1.0.0 (2025-10-28)

- 初始版本 - 三个核心工具：execute_bash_docker、list_mounts、install_package - Alpine Linux基础 - 可配置的卷装载 - FastMCP实施

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

资源

• MCP协议: https://modelcontextprotocol.io
• Docker文档: https://docs.docker.com
• 高山套餐: https://pkgs.alpinelinux.org
• FastMCP: https://github.com/modelcontextprotocol/python-sdk
• Claude桌面版: https://claude.ai/download

致谢

与 模型上下文协议 通过Anthropic。

______________________________________________________________________

问题或议题？ 在GitHub上打开问题或查看 故障排除 部分。