local-shell-mcp

local-shell-mcp

A self-hosted AI workspace and MCP control plane for shell, files, browsers, and remote machines.

Documentation · Quickstart · Runtime choices · Web workspace · Gemini Spark · ChatGPT connector · DSH plugin · Tools · Releases local-shell-mcp combines a self-hosted AI chat workspace with controlled access to a real execution environment. The unified browser UI is the recommended daily entry point; ChatGPT, Gemini and other external MCP clients remain supported. It exposes a dedicated workspace with shell, persistent shell, filesystem, search, patch, Playwright, audit, durable logical sessions with optional Goal plans, public file links, and outbound remote-worker access. Git is handled through ordinary shell commands instead of a parallel wrapper API.

The intended safety boundary is the container or VM, not the host. Why use it Quick start

Recommended deployment: the standalone single-file Controller executable from GitHub Releases. It bundles the Controller and native WebUI, runs without a system Python installation or Docker, and needs no repository checkout. Choose the matching binary for your OS/architecture; the following example is for Linux x86_64:

Create a private .env file with the necessary LOCAL_SHELL_MCP_ variables (see the quickstart). Use a strong OAuth PIN and the generated JWT secret, then start the executable with those variables explicitly exported:

Check http://127.0.0.1:8765/healthz and open the native UI at http://127.0.0.1:8765/ui. For remote access, prefer a public HTTPS server or reverse proxy; Cloudflare Tunnel is not recommended for file-heavy transfers. Keep OAuth enabled on publicly accessible endpoints.

The one-file executable is the Controller distribution, not an all-inclusive operating-system image. It uses host-installed task tools and optional external Playwright/browser dependencies. Integrated chat and projects use the separately deployed unified web workspace (Node.js, MongoDB, Meilisearch, and SearXNG); the remote Worker is distributed separately. No chat backend or database is claimed to be embedded in the Controller binary.

Other deployment methods remain supported: Docker Compose, Python/pipx/source, and the VS Code extension. See platform-specific binary installation for Windows, macOS, ARM64 and updates. Human interface

The recommended interface is the unified web workspace, which integrates chat and LSM Controller pages directly into a modified LibreChat React application. It uses the LSM login, stores chat projects and history on the server, and manages external tools through LSM's nested MCP registry. Its Node.js, MongoDB, Meilisearch and SearXNG services are optional, deployed separately from the lightweight Controller and Worker bundles.