# local-shell-mcp > Bridge all MCP tools from local-shell-mcp—including shell, file, browser, and remote machine—to the DeepSeek Harness web client, with a Live Workspace view for real-time collaboration. ## Metadata - Author: [@fwerkor](https://github.com/fwerkor) - Repo: - GitHub: [fwerkor/local-shell-mcp](https://github.com/fwerkor/local-shell-mcp) - Stars: 52 - Language: Python - License: [MIT](https://spdx.org/licenses/MIT.html) - Homepage: - Topics: `chatgpt-app`, `dsh-plugin`, `harness`, `mcp`, `remote-control` - Forks: 11 - Open Issues: 5 - Last push: 2026-08-20T06:48:45.000Z - Added: 2026-08-20T00:00:00.000Z ## Install ```bash dsh plugin --profile web add github:fwerkor/local-shell-mcp ``` ## Wiki ## One-Line Description Bridges the standalone local-shell-mcp MCP service (providing shell, file, browser automation, remote machine, Agent Skills tools, etc.) into DeepSeek Harness's web client, embedding a real-time collaborative Live Workspace panel within the conversation window. ## Core Capabilities - Automatically registers all upstream MCP service tools under the `mcp__lsm__*` namespace in the DSH tool list for direct model invocation - Injects upstream service-declared instruction segments as part of the system prompt, enabling the model to perceive currently available tools and context - Renders an embedded real-time workspace within the "Live Workspace" tab of the DSH session panel, supporting terminal viewing, files, task progress, and querying the model - Each DSH session gets its own dedicated upstream MCP connection, auto-disconnected when the session ends, with heartbeat and reconnection on disconnect - Listens to upstream `tools/list_changed` notifications, hot-updating the local tool list without restarting the plugin - Non-text content like images, audio, and resources returned from upstream are discarded and replaced with placeholder descriptions to avoid polluting the conversation context ## Technical Implementation - **Language**: JavaScript (Node.js, ESM) - **Key Dependencies**: `@modelcontextprotocol/sdk` (MCP client), `zod` (result validation), `node:crypto`, `node:fs/promises` - **Architecture Pattern**: DSH bundle patch + client injection dual-end structure; server side bridges MCP through four hooks: `tools` / `systemPrompt` / `webServer` / `agents`, client side mounts React views in the conversation panel via `slots` / `sessions` / `conversation` - **Entry Files**: `dsh/index.js` (server-side bridge), `dsh/client.js` (client-side React view), `cordis.patch.yml` (injection declaration) ## Use Cases When you already have a local-shell-mcp service running locally or in a container and want DeepSeek Harness to directly call it for command line, file operations, browser automation, and remote machine control, installing this plugin brings the complete toolset and real-time workspace into the DSH web interface. Particularly convenient for multi-account collaboration or when you need to visually display the model's execution process. ## Prerequisites & Compatibility | Dependency | Minimum Version | Description | |---|---|---| | DSH | Not declared | Injects via `dsh.bundle.patch` and `dsh.client.inject`, requires DSH version supporting bundle patch and client runtime | | Node.js | >=22 | Declared in package.json engines field | | Platform | Cross-platform | Pure Node.js implementation with no native modules, relies on `node:crypto` / `node:fs/promises` | | Local MCP Service | Bundled | Depends on upstream local-shell-mcp HTTP service at default address `http://127.0.0.1:8765/mcp`, needs to be started separately | ## Installation ```bash dsh plugin --profile web add github:fwerkor/local-shell-mcp ``` ## Configuration This plugin requires no manual configuration from regular users; the following advanced fields take effect under `config` in `cordis.patch.yml` (can also override defaults via similarly-named `DSH_LSM_*` environment variables): | Configuration | Type | Description | Default Value | |---|---|---|---| | url | String | HTTP/HTTPS address of the upstream MCP service; DSH establishes a Streamable HTTP connection to it | `http://127.0.0.1:8765/mcp` | | browserUrl | String | Frontend origin address for the Live Workspace browser panel; if not set, uses the address returned by upstream | Not set (passthrough from upstream) | | headers | Object | Extra HTTP headers to passthrough to upstream MCP requests, such as `Authorization` | Empty object | | toolCallTimeoutMs | Number | Maximum wait time for a single tool call; exceeding this will interrupt | `120000` (120 seconds) | | keepAliveIntervalMs | Number | Heartbeat interval; must be at least 5000 milliseconds | `30000` (30 seconds) | | reconnectInitialDelayMs | Number | Milliseconds to wait for first reconnection after upstream disconnect | `500` | | reconnectMaxDelayMs | Number | Maximum backoff wait milliseconds for reconnection | `30000` | Environment variable quick overrides: `DSH_LSM_MCP_URL` / `DSH_LSM_BROWSER_URL` / `DSH_LSM_AUTHORIZATION` / `DSH_LSM_TOOL_CALL_TIMEOUT_MS` / `DSH_LSM_KEEPALIVE_INTERVAL_MS`. ## FAQ **Q: What will I see after installing?** A: A "Live Workspace" tab will appear in the conversation panel, showing local-shell-mcp's real-time collaborative interface (terminal, files, task progress, etc.). The model's available tools list will also automatically append all upstream-declared tools with the `mcp__lsm__` prefix. **Q: Do I need to start the local-shell-mcp service first?** A: Yes. This plugin is just a bridge and doesn't include the MCP service internally; it depends on the upstream MCP service at localhost:8765 (default). You can change the address via the `DSH_LSM_MCP_URL` environment variable or the `url` field in `cordis.patch.yml`. **Q: Is each DSH session independent?** A: Yes. The plugin establishes a separate upstream MCP connection for each DSH Session, tagged with session affinity request headers. It maintains up to 64 active session connections simultaneously; when exceeded, sessions are evicted based on least recently used time for ended sessions. **Q: What if tool results contain images or audio?** A: The plugin only forwards text fragments to the model. Images, audio, and `resource` content are replaced with placeholders like "[image: …, content discarded]" to prevent large binary data from flooding the conversation context. **Q: Do I need to add a Bearer Token for the local service?** A: Optional. Set `DSH_LSM_AUTHORIZATION` in the DSH process environment to passthrough to upstream MCP request headers; alternatively, hardcode it in the `headers` field of `cordis.patch.yml`. **Q: Will DSH automatically update when the upstream MCP tool list changes?** A: Yes. The plugin subscribes to upstream `tools/list_changed` notifications. Upon detecting changes, it re-fetches and hot-updates the local `mcp__lsm__*` tool list without restarting the plugin or reconnecting the session. **Q: What if the Live Workspace fails to load?** A: First verify the upstream MCP service is reachable and the `live_workspace_reconnect` tool has returned credentials. If the upstream is remote HTTPS and DSH is accessed in a browser, you also need to properly set `DSH_LSM_BROWSER_URL`; otherwise iframe cross-origin or protocol mismatches will cause failures. ## Learning Curve Beginner — single command installation; main work is starting a local-shell-mcp MCP service that can be accessed, with no additional DSH-side configuration required. ## Known Issues & Limitations - Upstream tools that require "task-based" execution mode will cause this bridge to throw an error without calling them, as the current implementation only supports standard request/response-style tool calls - Maximum number of active DSH session connections is 64; when 64 sessions are all still active and a new session wants to connect, it will directly throw a "too many live sessions" error instead of queuing - Upstream returned images, audio, and `resource_link` content are discarded; the model only receives placeholder descriptions and cannot directly view or forward them - `cordis.patch.yml`'s `browserUrl` cannot contain username and password, otherwise configuration validation will error - Tool names undergo length and character normalization (`mcp__lsm__` prefix + truncation + hash); upstream tool names that are too long will appear differently in the DSH UI than their original names --- This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [local-shell-mcp](https://deepseek-plugin.org/plugins/fwerkor/local-shell-mcp) Wiki generated by AI (model: `MiniMax-M2.7`)