mcp-shell-tools

mcp-shell-tools

Workstation tools: files, editing, searching, running commands, notes thatsurvive a restart, and a look at the machine.

Three ways to use them, all on the same code:

• as a server — mcp-shell-tools serve, over stdio or HTTP
• as a plugin — loaded by the MCP proxy
• as a library — from mcp_shell_tools import _files and call the functions

Only the server touches the MCP SDK, and only through server.py. The toolsthemselves know nothing about the protocol, which is why the same module worksin all three.

Coming from version 4

The command mcp-shell-tools works as before, with serve in front of it:mcp-shell-tools serve instead of mcp-shell-tools. The 4.x releases havebeen withdrawn from PyPI, so there is nothing to fall back to.

Two differences in the tool set: the tool command is gone, because it steeredlogging in the old server and the logging concept it needs does not exist inthis one. And version 5 needs Python 3.12, where version 4 ran on 3.10.

Installation

pip install mcp-shell-tools            # tools, command line, plugin
pip install "mcp-shell-tools[server]"  # and the standalone server

As a server

mcp-shell-tools serve                                   # stdio
mcp-shell-tools serve --transport streamable-http --port 8000

In a client that starts the server itself:

{
  "mcpServers": {
    "shell": {
      "command": "mcp-shell-tools",
      "args": ["serve", "--working-dir", "/home/you/projects"]
    }
  }
}

--allowed-root confines the tools to a directory and may be repeated.Without it they may touch the whole disk.

On the command line

Every tool is a subcommand. Paths keep their place on the line, numbers andswitches are flags.

mcp-shell-tools file_list src
mcp-shell-tools grep "def register" --glob "**/*.py"
mcp-shell-tools head CHANGES.md --lines 20
mcp-shell-tools find_replace alt neu --apply
mcp-shell-tools sysinfo

The subcommands are read from the tool set itself, so a tool added to theplugin appears here without anything being written twice.

What it publishes

Thirty-three tools, in eight groups. Names are given without prefix; the proxyputs one in front of them.

file_write earns its place next to exec: a heredoc inside a long commandline is where quoting goes wrong, and writing a file is too common to leave tothat.

find_replace does nothing until apply is true, and it never descends into.git, .venv, node_modules or __pycache__. A rewrite across many filesshould be read before it happens, and it has no business inside a repository'sown bookkeeping.

ps reports memory, not a CPU share. A share is a measurement over a span oftime, and a single listing has no span to measure over.

Interface

A module with register(mcp, config). What arrives as mcp is the proxy'sregistrar rather than an SDK server, so this package needs neither the SDK northe proxy to be imported or tested. Ruff refuses an import from mcp anywherein it. The only runtime dependency is psutil, which the machine tools use.

Configuration

Read by the proxy from <plugin-dir>/shell/config.yaml:

prefix: "shell_"                  # put in front of every tool name
working_dir: /home/ucuber/Workspace
timeout: 120                      # seconds a command may run
max_output: 200000                # characters of output kept
max_results: 200                  # rows a listing or search returns
state_dir: /home/ucuber/.mcp-shell-sessions
allowed_roots: []                 # empty means no limit

allowed_roots confines every path the tools touch. Left empty there is nolimit, which is what a workstation tool set is for; set it when the proxy isreachable by someone who should not have the whole disk.

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests
pylint src tests
pytest

Use in the proxy

~/Workspace/projects/mcp-tools/mcp-proxy/.venv/bin/pip install -e .

Then --load mcp_shell_tools.shell in the unit, or proxy_load with thatreference while the proxy runs.