local-shell-mcp

📌 一句话定位

local-shell-mcp 是一款 ChatGPT 兼容的 MCP 控制平面，为 AI 编程 Agent 提供受控的 Shell 文件系统、浏览器自动化、远程主机访问和 Agent Skill 加载能力，在隔离的容器或虚拟机边界内安全执行。

🔧 核心功能

💻 全面的执行环境

Shell 与持久会话：提供标准 run_shell 和持久化 shell_* 系列工具，支持 Git CLI 工作流、测试运行、项目构建、日志调试，无需第二个不完整的 Git 封装层。

文件系统工具：在受控工作区根目录下执行文件读取、写入、搜索、补丁和审查操作，所有路径自动限定在 /workspace 内。

Playwright 浏览器自动化：内置高级浏览器工具，支持页面截图、PDF 抓取、全功能 Playwright 脚本执行，适用于自动化测试和数据采集场景。

远程 Worker 支持：可控制 NAT 防火墙后、HPC 集群、NPU/GPU 服务器等只能向外发起连接的远程机器，无需开放任何入站端口。

🤖 Agent Skill 加载能力

通过三个固定工具（skill_list、skill_load、skill_read）自动发现和加载可复用的 Agent Skill 工作流，无需修改 MCP 工具列表或重连客户端。Skill 来源支持项目级、全局用户级和工具安装级三层优先级覆盖。

💬 ChatGPT 深度集成

原生支持 ChatGPT MCP App，提供实时 Activity、终端、文件浏览器、Diff 视图、Jobs、远程管理和审计面板。session_manage 为 Agent 工作提供持久化的任务上下文，新对话可一键继承历史进展；plan_manage 支持可选的 Goal 模式，对复杂多步任务自动规划与续接。

🛡️ 安全模型

默认保护机制包括：

• 工作区路径限定在 /workspace，除非显式开启全容器模式
• 命令超时、输出限制和并发限制
• 默认命令/路径黑名单过滤
• Shell 子进程环境变量过滤
• 动态 MCP 服务器仅继承最小化操作系统环境
• 审计日志记录所有 Agent 发起的 MCP 活动
• 敏感信息扫描辅助

硬性安全规则：不挂载 Docker Socket、不挂载宿主机根文件系统、不在公共网络关闭鉴权。

🚀 快速上手

# npm 方式（自动下载匹配的独立可执行文件）
npx local-shell-mcp --help

# pipx 方式
pipx install local-shell-mcp

# Docker 启动
git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env
mkdir -p workspaces/default
docker compose up -d

# 访问 Web 控制台
curl http://127.0.0.1:8765/ui

📡 MCP 工具一览

💡 典型使用场景

私有 GitHub Actions / CI 执行：在隔离容器中通过 Shell 工具触发构建流程，AI 实时查看日志、下载产物，无需开放额外 API 端口。

跨云远程开发：在防火墙严格的 GPU 服务器上启动 outbound-only Worker，AI 通过 remote_transfer 推送代码、run_shell 执行训练脚本，全程无需 SSH 端口暴露。

需要真实浏览器的数据采集：AI 直接调用 Playwright 工具执行完整的浏览器自动化任务（登录、表单、滚动截屏），结果以内置截图/HTML 形式返回。

多 Agent 协作与任务续接：使用 session_manage 为每个任务建立持久化会话，AI 可随时通过 session_manage(action="resume") 继承之前的工作上下文继续执行。

🐳 部署方式

支持五种运行时：Docker（推荐）、VS Code 扩展包、独立可执行文件、Python 直接运行、stdio 直连模式。可根据安全边界需求（本地隔离 / 远程 HTTPS 暴露）灵活选择。

📦 信息速览

• 类型：MCP 服务器 / 编程 Agent 执行环境
• 许可：MIT
• Python 版本：≥ 3.11
• 文档：https://fwerkor.github.io/local-shell-mcp/
• GitHub：https://github.com/fwerkor/local-shell-mcp