fwerkor/local-shell-mcp

local-shell-mcp

一个面向 ChatGPT 的 MCP 控制平面，用于 shell、文件、浏览器自动化、文件链接和远程机器。

Docs
CI
dsh.so security
Release
Python
Docker
License

文档 · 快速开始 · 运行时选择 · ChatGPT 连接器 · DSH 插件 · 工具 · 版本发布

local-shell-mcp 为 ChatGPT Developer Mode 和其他 MCP 客户端提供对真实执行环境的受控访问。它暴露一个专用工作区，包含 shell、持久 shell、文件系统、搜索、补丁、Playwright、审计、带可选 Goal 计划的持久逻辑会话、公共文件链接以及出站远程 worker 访问。Git 通过普通 shell 命令处理，而不是通过一个并行的包装 API。

Runtime: Docker / VS Code extension / binary / Python / stdio
-> exposure: localhost, HTTPS proxy/tunnel, or stdio pipe
-> client: ChatGPT or another MCP client
-> controlled workspace at /workspace or configured root
-> optional remote workers connected over outbound HTTP(S)

预期的安全边界是容器或虚拟机，而不是宿主机。

为什么使用它

| 能力 | 它能实现什么 |
|---|---|
| 真实终端访问 | 运行测试、构建项目、检查日志，并通过持久 shell 会话进行调试。 |
| 工作区感知的文件工具 | 在受控根目录下读取、写入、打补丁、搜索和审查文件。 |
| Git 工作流支持 | 通过 shell 工具运行标准 Git CLI，而无需第二个不完整的 Git 抽象。 |
| 浏览器自动化 | 提取页面文本、捕获 PNG/PDF 证据，或运行完整的 Playwright 脚本。 |
| 远程工作节点 | 控制只能向外连接的 NAT、防火墙、HPC、NPU 或实验室机器。 |
| Agent Skills | 通过三个固定工具发现、加载和读取可复用的 SKILL.md 工作流，而无需更改 MCP 工具列表。 |
| ChatGPT 连接器支持 | OAuth 2.1、/mcp、发现控制，以及兼容 ChatGPT 的工具 schema。 |
| DeepSeek Harness 插件 | 将此仓库安装为 DSH 捆绑包，并暴露完整的 LSM 工具面，包括远程工作节点。 |
| ChatGPT 实时工作区 | 渲染原生 MCP App，用于在 ChatGPT 内实时展示活动、终端、文件、差异、任务、远程节点、审计，以及直接的人机/智能体协作。 |
| 更安全的操作 | 工作区作用域、shell 超时、输出限制、环境过滤、审计日志和密钥扫描。 |

快速开始

当你需要宿主运行时，安装官方启动器或 Python 包：

npx local-shell-mcp --help
pipx install local-shell-mcp
lsm --help

npm 和 Python 发行版都提供 local-shell-mcp；已安装的包还提供 lsm 作为短命令。npm 发行版只是用于匹配的独立发布二进制的经验证启动器，而不是第二个服务器实现。

克隆仓库并准备配置：

git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env

在 .env 中至少设置以下值：

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com
LOCAL_SHELL_MCP_AUTH_MODE=oauth
LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN=change-me-long-random-pin
LOCAL_SHELL_MCP_OAUTH_JWT_SECRET=change-me-64-hex-random-secret
CLOUDFLARE_TUNNEL_TOKEN=

启动服务器：

mkdir -p workspaces/default
docker compose up -d
curl -i http://127.0.0.1:8765/healthz

当你需要公共 HTTPS 访问时，启动捆绑的 Cloudflare Tunnel sidecar：

docker compose --profile tunnel up -d

公共 MCP 端点为：

https://your-public-host.example.com/mcp

完整设置说明见文档。运行时选择与客户端连接分别记录。

人机界面

该服务包含两个兼容的人机界面，由同一套经过身份验证的 API 和状态提供支持：

- Web UI 是一个原生浏览器仪表板，用于展示系统健康状况、机器、工作负载、最近的 MCP 活动和警报。
- OpenTUI 是完整的面向终端的界面，包含 Dashboard、Files、Terminals、Remotes 和 Audit 屏幕。它仍可在浏览器中作为可选择的控制台使用，也可通过原生 local-shell-mcp tui 命令使用。

在服务源上打开浏览器界面：

http://127.0.0.1:8765/ui
OAuth 界面允许你在授权前选择 Web UI 或 OpenTUI。登录后，可随时通过界面选择器切换模式。原生 Web UI 路由使用 URL 哈希，例如 #/overview 和 #/console，因此所选的模式或页面可以被添加为书签。OpenTUI 控制台保留了现有的已认证 xterm.js/PTY 传输、鼠标交互、自动调整大小、重新连接、全屏模式以及移动端快捷行。

独立发布的可执行文件内嵌了原生 OpenTUI 运行时，而 Docker 镜像则在镜像内部提供它。启动服务后，无需人工登录提示即可启动它：

local-shell-mcp tui

Files 仍然是 OpenTUI 内 LSM 原生的三窗格文件管理器，适用于本地和远程机器。它渲染有大小限制的 PNG/JPEG/GIF/WebP 缩略图，并通过共享服务 API 提供一致的文件操作。通过任一人机界面输入的手动操作不纳入 MCP 审计日志；Activity、Audit 和终端审计栏显示源自模型的 MCP 活动。

参见人机界面指南。

ChatGPT 设置

要使用完整的 shell、文件系统、远程工作器和 Playwright 工具，请使用 ChatGPT 开发者模式或其他完整的 MCP 客户端。ChatGPT 是一种客户端连接；请先选择并启动一个运行时。

session_manage 为智能体工作提供一个持久的逻辑任务上下文。Session 有意独立于机器和工作目录：它存储任务目标、语义进度报告、最近的执行 Activity 以及可选的 Plan。session_id 是唯一持久的任务标识。要在另一个 ChatGPT 对话中继续工作，用户需显式传入现有的 session_id，新智能体调用 session_manage(action="resume", session_id=...)。智能体不会列出或自动选择来自其他对话的 Session。它们应在启动/恢复后、在有意义的进度检查点以及结束一轮之前报告活动的 session_id，同时使用 session_manage(action="report", session_id=...) 进行语义进度报告，而不是将每个工具结果都复制到摘要中。普通工具接收与 logical_session_id 相同的任务标识。
当客户端支持 MCP Apps 时，workspace_open(session_id=...) 会为显式选定的 Session 以浮动 MCP App 的形式打开执行视图，并可展开至全屏。v3 名称 open_live_workspace 仍作为隐藏的、未枚举的兼容别名，供缓存了 recipient 的 ChatGPT 客户端使用；新集成只会看到并使用 workspace_open。Live Workspace 是一个可重连的查看器与协作界面，而非任务状态的拥有者：关闭它或重连 MCP 不会丢弃 Session 进度、Activity 或其 Plan。普通 MCP 工具仍是执行 API，而该应用则增加了实时操作活动、持久终端、文件/差异检查、jobs、remotes、审计数据以及活动 Session id。不渲染 MCP Apps 的客户端继续使用不变的常规工具界面。

plan_manage(session_id=...) 可选地为该显式 Session 启用 Goal mode，用于大量多步骤工作。活动 Plan 即为目标：其步骤可随执行变化而修订，并且在 Live Workspace 已附加时，应用可在 15 分钟无 agent 工具活动后请求继续。自动继续最多为 10 次继续尝试（无论接受或拒绝），并在继续前恢复同一 Session。Blocked、completed 和 cancelled 的 Plan 状态绝不会被催促；若活动 Plan 的所有步骤均已完成或跳过，则仍符合清理继续的条件，以便恢复的 agent 可以调用 plan_manage(action="finish")。Session 不要求必须有 Plan。

1. 通过 HTTPS 暴露服务器。
2. 保持 OAuth 启用。
3. 添加 MCP 端点：https://your-public-host.example.com/mcp。
4. 完成 OAuth 授权流程。
5. 从有界任务开始，并在需要时检查审计日志。

阅读专门的 ChatGPT connector 指南。

DeepSeek Harness 插件

dsh.so install

仓库根目录同时也是一个 DSH 插件包。在同一主机上运行正常的 LSM HTTP/MCP 服务后，可直接将其安装到 DSH 配置文件中：

dsh plugin --profile web add 'github:fwerkor/local-shell-mcp#main'

该包使用 LSM 感知的 Streamable HTTP 桥接，并保留完整的 LSM 工具界面，包括 remote_manage、remote_transfer、浏览器工具以及 Dynamic MCP 工具。每个 DSH Session 都会获得一个稳定的 v4 逻辑会话身份，因此其 Logical Session、活动运行、Activity 以及原生 Live Workspace 视图与其他 DSH 对话保持隔离，并在 DSH 侧 MCP 传输重建后依然存在。DSH 在常规 mcp__lsm__ 命名空间下看到模型工具。对于生产环境，请将 Git 规格固定到经过审查的 release 或 commit。

参见 DeepSeek Harness 集成指南。

VS Code 扩展运行时
发布资产包含 local-shell-mcp-.vsix。该扩展是当前 VS Code 工作区的运行时启动器。它启动相同的服务器，检查 /healthz，复制 MCP URL，并复制一份可直接粘贴的 ChatGPT 设置提示。

基本流程：

安装可执行文件 -> 安装 VSIX -> 打开工作区 -> 启动服务器 -> 复制 MCP URL

若要公开访问 ChatGPT，请通过 HTTPS 隧道暴露本地服务器，并在 VS Code 设置中设置 local-shell-mcp.publicBaseUrl。直接使用宿主机时，请保持 local-shell-mcp.allowFullContainer 处于禁用状态；仅在一次性容器或虚拟机中启用它。

远程工作节点

远程工作节点模式默认启用。在控制服务器上创建一次性邀请，将生成的命令粘贴到远程机器上，然后使用带有可选 machine 参数的常规工具。只有工作节点管理保留 remote_ 名称。

这适用于：

- 位于防火墙后的 HPC 登录节点或计算节点。
- 没有入站连接能力的 NPU/GPU 服务器。
- 可以发起出站 HTTPS 请求的实验室机器。
- 临时构建主机或远程测试环境。

请参阅远程工作节点指南。

Agent Skills

Skills 从三个有序来源发现：项目级 /workspace/.agents/skills、LSM 管理的 /workspace/.local-shell-mcp/agent_config/skills，以及全局 ~/.config/agents/skills。优先级更高的来源会覆盖同名的低优先级 Skills，并且支持符号链接的 Skill 目录和文件。

这使得通用 Skills CLI 布局可以直接使用，例如 npx skills add owner/repo --agent universal -y。使用 skill_list 发现已安装的 Skills，使用 skill_load 加载一组指令，使用 skill_read 通过返回的相对于 Skill 的路径读取相关文件。更改会在下次调用时被检测到；不会注册每个 Skill 的 MCP 工具，也不需要客户端重新连接。

请参阅 Agent Skills 指南。

工具面

公开的 MCP 工具面包括：

- 实时工作区：workspace_open 为当前逻辑会话打开可重新连接的 MCP App。
- Shell 和作业：run_shell、run_python、持久化的 shell_，以及受跟踪的 job_ 工具。使用 run_shell 执行 Git CLI 操作。
- 文件系统：file_list、file_tree、file_glob、file_grep、统一的 file_read、原生视觉 image_view、file_write、统一的 file_edit、file_delete 和 file_patch。
- 传输：remote_transfer 用于在控制器和工作节点端点之间传输文件或目录。
- 动态 MCP：mcp_manage、mcp_tool_search、mcp_tool_inspect 和 mcp_tool_call。外部工具会被逐步发现，并且绝不会扩展 LSM 自身的 tools/list 工具面。
- 浏览器：持久化的高层 browser_session、browser_snapshot 和 browser_act；browser_run_script 是低层 Playwright 逃生通道。
- 文件链接：link_create、link_list、link_revoke。
- 远程工作节点：remote_manage，支持 invite、list、rename 和 revoke 操作；常规执行工具接受可选的 machine。
- Agent Skills：skill_list、skill_load、skill_read。
- 会话：session_manage，用于持久化任务上下文、进度交接、代理运行接管以及跨运行继承。
- 规划：plan_manage，用于可选的 Session 拥有的 Goal 模式和自动延续。
- 诊断：environment_get（包括版本信息）、secret_scan 和 audit_tail。

每个工具的详细参考，包括用途、输入、返回、组合和注意事项，可在文档中查看。

相关项目

以下独立维护的项目探索了围绕 LSM 的相邻会话和编排模型：

- rijuyuezhu/local-shell-mcp 使用一种不同的、面向执行的会话模型，将工作区上下文和相关资源绑定到显式会话。它有自己的工具界面和发布生命周期。
- DongYaoZe/localshell-web-supervisor 是一个本地可靠性和编排层，用于使用 Local Shell MCP 的浏览器驱动代理。它监督可替换的浏览器工作节点，同时协调持久化的 LSM 会话、Goals/jobs 以及实际的工作区/Git 状态，并具有受保护的租约、交接、接管和恢复流程。它不属于 LSM 运行时或发布生命周期的一部分。

安全模型

本项目有意暴露强大的工具。请将连接的模型视为拥有容器或虚拟机的控制权。

默认保护措施包括：

- 除非显式启用全容器模式，否则工作区范围限定为 /workspace。
- 命令超时、输出限制和并发限制。
- 针对主机控制片段的默认命令/路径拒绝列表。
- 针对服务端密钥的 Shell 子进程环境过滤。
- 动态 stdio MCP 服务器仅继承最小操作系统环境以及显式配置的每服务器变量；配置的环境/头值存储在模式为 0600 的状态文件中，并从工具结果和 Audit 参数中脱敏。
- 审计日志位于 /workspace/.local-shell-mcp/audit.jsonl。
- 在提交和推送之前进行密钥扫描辅助。
- 具有 TTL/下载限制和撤销功能的令牌化文件链接。

硬性规则：

1. 不要挂载 /var/run/docker.sock。
2. 不要挂载主机根文件系统。
3. 不要在公共网络上使用 LOCAL_SHELL_MCP_AUTH_MODE=none 暴露服务。
4. 不要将长期凭证放入模型可见的环境变量中。
5. 优先使用单仓库部署密钥或短期令牌。
6. 在一次性容器或虚拟机中运行服务。
7. 将 local-shell-mcp-credentials Docker 卷视为敏感数据。

有关漏洞报告，请阅读 SECURITY.md。

配置
复制 .env.example 以进行标准设置。配置参考 记录了每个环境变量以及用于高级部署的可选 YAML 格式。

重要选项：

| 设置 | 用途 |
|---|---|
| LOCAL_SHELL_MCP_PUBLIC_BASE_URL | OAuth 和 ChatGPT 使用的公共 HTTPS 源。 |
| LOCAL_SHELL_MCP_AUTH_MODE | 对于公共部署，使用 oauth。 |
| LOCAL_SHELL_MCP_ALLOW_FULL_CONTAINER | 仅在一次性容器/虚拟机中禁用工作区限制。 |
| LOCAL_SHELL_MCP_REMOTE_ENABLED | 启用或禁用远程工作进程控制工具。 |
| LOCAL_SHELL_MCP_UI_ENABLED | 挂载或禁用共享的 OpenTUI/WebUI 人机界面。 |
| LOCAL_SHELL_MCP_UI_PATH | 同一服务上的 WebUI 挂载路径；默认为 /ui。 |
| LOCAL_SHELL_MCP_UI_WALLPAPER | 为 OpenTUI 浏览器控制台背景选择 bing、aurora 或 none。 |
| LOCAL_SHELL_MCP_SHELL_ENV_BLOCKLIST | 从生成的 shell 进程中移除的环境变量。 |
| LOCAL_SHELL_MCP_FILE_DOWNLOAD_ENABLED | 启用带令牌的文件下载链接。 |

开发

安装开发依赖并运行检查：

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,docs]'
ruff check .
pytest -q
mkdocs build --strict

构建 VS Code 扩展：

npm --prefix vscode-extension install
npm --prefix vscode-extension run compile

贡献工作流程记录在 CONTRIBUTING.md 中。

项目文档

- 文档站点
- 贡献指南
- 安全策略
- 行为准则
- 支持指南
- OAuth 设置
- 许可证