shell2mcp

Serve a folder as an MCP server that offers the same coding tools as the Pi agent: read, bash, edit, write, grep, find and ls. Tool names and parameter schemas match Pi's, so a model that knows Pi's tools can use them as is. Pure Python standard library, no dependencies.

By itself it listens on 127.0.0.1 only. Nothing leaves your machine unless you add --tunnel or run your own tunnel.

Install and run

pip install shell2mcp          # or: uvx shell2mcp
shell2mcp                      # serve the current folder on 127.0.0.1:8765 (a free port if that is taken)

The MCP URL is printed on stdout (everything else goes to stderr), for example http://127.0.0.1:8765/3f9c.../mcp. The random path segment is the only access control, so treat the URL as a secret.

shell2mcp [--root DIR] [--port N] [--secret S] [--read-only] [--tunnel] [--version]

With cloudflared

Built in:

shell2mcp --tunnel                 # prints https://<random>.trycloudflare.com/<secret>/mcp
URL=$(shell2mcp --tunnel | head -1)   # the URL is the only thing on stdout

Or run the tunnel yourself, since the server is a plain local HTTP endpoint:

shell2mcp --port 8765 &
cloudflared tunnel --url http://127.0.0.1:8765
# MCP URL: https://<random>.trycloudflare.com/<secret>/mcp  (the secret is printed by shell2mcp)

Add that URL as a remote MCP server (Streamable HTTP, no auth) in any MCP client.

Tools

Paths are relative to --root; absolute paths and .. that leave it are rejected.

Security

bash runs real commands. The folder restriction applies to the file tools, but a shell command can still read other files your user can read. Only tunnel it on a machine and account you are happy to expose, prefer a throwaway folder or container, use --read-only when you can, and stop it when you are done. Everything the model reads is sent to whichever model provider the MCP client uses.

License

MIT