Skip to content

local-shell-mcp

local-shell-mcp lets ChatGPT and other MCP clients work in a controlled project workspace. It can inspect and edit files, run commands and tests, use Git, manage persistent terminals, and delegate work to registered remote machines.

This project is an independently maintained, session-oriented fork of fwerkor/local-shell-mcp. The projects now have different tool contracts, lifecycle models, capabilities, and release lines. See Comparison with upstream for the major functional differences.

Start here

  • Follow the Quickstart for a local service exposed through HTTPS.
  • Use Docker Compose when you prefer an isolated container deployment.
  • Add the service to ChatGPT or VS Code.
  • Review Security before exposing the service outside localhost.

What users can do

After connecting an MCP client, start an explicit workspace session and ask it to:

  • inspect a repository and its instruction files;
  • search, read, edit, and patch project files;
  • run tests, build commands, and Git workflows;
  • keep long-running jobs or persistent terminals;
  • copy data between local and remote sessions;
  • review Todos and Audit history;
  • use configured Skills or upstream MCP servers.

See Common workflows for practical examples and the generated Tool reference for exact tool contracts.

Human and remote access

The HTTP server includes a browser interface at /ui. An optional terminal client provides the same main management areas. See Human interface.

To work on another machine while keeping one public MCP endpoint, enroll a remote worker.

Warning

Give the service access only to workspaces you are prepared for an AI coding agent to modify. Keep OAuth enabled for public deployments, use narrow scopes, and leave full-control mode disabled unless the environment is disposable.