local-shell-mcp
An MCP server giving ChatGPT and agents a terminal, files, Playwright and remote machines inside an isolated workspace.
- 106 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent runs arbitrary commands and edits files, and the server can be exposed to the internet through a tunnel.
Install
- Works in
Manual install
npx local-shell-mcp --helpThe first Quick start command runs the official launcher; the server then needs `.env` and `docker compose up -d`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent runs arbitrary commands and edits files, and the server can be exposed to the internet through a tunnel.
This is third-party code. Review the repository files before installing.
What it does
local-shell-mcp gives an MCP client a real execution environment: persistent shell sessions, file operations, search, patching, Playwright and audit. Git runs through the ordinary CLI. It adds durable logical sessions with an optional goal plan, and public file links. It runs through Docker, a VS Code extension, a binary, Python or stdio, and connects to ChatGPT over HTTPS with OAuth 2.1. Remote workers connect outbound, so machines behind NAT or a firewall are reachable. The server also reads `SKILL.md` workflows through three fixed tools.
Who it is for. Developers and administrators who want to give ChatGPT or another MCP client a working shell on their own server or container.
Good fit when
- ChatGPT in developer mode must run tests and builds on your machine.
- An agent needs a persistent terminal and file edits in one workspace.
- You manage a lab machine behind NAT through an outbound connection.
- A task spans several conversations and continues by session id.
Not a fit when
- The server would run on a personal machine with live secrets and no container or VM.
- Internet exposure without OAuth is unacceptable.
- You only need code search without running commands.
Example request
Run the project tests in the workspace, show the failing ones and fix the file without touching the rest.MCP
- Transport
- http, stdio
- Authentication
- OAuth
Environment variables
LOCAL_SHELL_MCP_PUBLIC_BASE_URLrequired- Public HTTPS address of the server.
LOCAL_SHELL_MCP_OAUTH_ADMIN_PINrequired- Admin PIN for OAuth login.
LOCAL_SHELL_MCP_OAUTH_JWT_SECRETrequired- Secret used to sign OAuth tokens.
Limitations
The authors define the safety boundary as the container or VM, not the host. The agent runs arbitrary commands and edits files, so running it on a working machine without isolation is risky. Public access needs an HTTPS address, OAuth and a strong admin PIN; the bundled Cloudflare tunnel needs a token. The VS Code extension should keep `allowFullContainer` off outside disposable containers.
How to disable. Stop the service (`docker compose down` or end the process), remove the connector from ChatGPT or the MCP client and close the tunnel. Delete the state directory, the `.env` with tokens and the audit log separately.
FAQ
Docker or a binary?
Both work, along with VS Code, Python and stdio. The README advises keeping the safety boundary at the container or VM.
How do I connect ChatGPT?
Expose the server over HTTPS, keep OAuth on, add `https://your-public-host.example.com/mcp` and complete authorization.
Is there a web interface?
Yes, a dashboard at `http://127.0.0.1:8765/ui` and a terminal OpenTUI launched with `local-shell-mcp tui`.
How do I call a tool from a script?
Use `lsm call`, for example `lsm call run_shell --json '{"command":"uname -a"}'`, with a separate local CLI token.
Does it work with DeepSeek Harness?
Yes, the bridge installs as `dsh plugin --profile web add local-shell-mcp-dsh` while the server runs locally.
Discussion
No questions or reviews yet.
Related
MCP serversA WebSSH console for VPS with an MCP server: the agent works across several servers while ACL tokens limit tools and hosts.
Console Automation MCP gives an agent local shells and SSH sessions: input, output, error detection, long processes
MCP server giving an agent a PowerShell 7 console shared with the user: commands appear live, passwords and MFA codes stay manual.
SSH MCP Server (classfang): remote commands over SSH
SSH MCP Server (classfang)
An SSH MCP server: the agent runs commands, reads and writes files over SFTP, transfers files and starts long jobs while credentials stay with you
Your machine's terminal, windows and desktop in a browser, plus an MCP server for agents to read and type into other sessions
Self-hosted MCP server for running commands on remote servers over SSH, with tokens and roles
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| local-shell-mcp (this card) | no | OAuth | 106 | |
| Desktop Commander MCP | no | not required | 10,294 | works on the user's local machine; local-shell-mcp targets a container, OAuth for ChatGPT and remote workers |
| headless terminal | no | 122 | provides a terminal session; this adds files, Playwright, audit and logical sessions with a plan |
README in short
The repository describes a ChatGPT-ready control plane for shell, files, browser and remote machines, with Docker Compose, binary releases, a VS Code extension and a separate documentation site.