Shell Tools

Version 8.0 — completely rewritten and revised.

Workstation tools for AI assistants: files, editing, searching, shell commands, notes, sessions and a look at the machine. Thirty-three tools, usable as a Python library or served over the Model Context Protocol.

• Library: plain functions grouped by subject, no dependency beyond psutil, nothing about MCP.
• Server: the same tools over stdio or streamable HTTP with the MCP SDK, protocol revision 2026-07-28, OAuth for HTTP.
• Boundary: reading reaches the whole system, writing stays inside allowed roots and /tmp, shell commands are off. A person on the host widens or narrows that for a limited time with a grant.

Installation

Python 3.12 or later.

pip install mcp-shell-tools            # the library
pip install "mcp-shell-tools[server]"  # and the MCP server

Quick start

A client that starts the server itself, over stdio:

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

Over HTTP, with OAuth:

MCP_OAUTH_ENABLED=true \
MCP_OAUTH_SERVER_URL=https://auth.example.org/ \
MCP_PUBLIC_URL=https://mcp.example.org/ \
mcp-shell-tools --transport streamable-http --host 0.0.0.0 --port 12204 --path /shell

As a library:

from pathlib import Path

from mcp_shell_tools import Workspace, files, find

space = Workspace(working_dir=Path.cwd())
print(files.file_read(space, "README.md"))
print(find.grep(space, "def main", glob="**/*.py"))

What the server allows by default

Reading goes anywhere. Writing, deleting and moving stay below the home directory. Shell commands do not run. A refusal says which grant lifts it:

outside the allowed roots for write: /etc/example.conf; a person on the host
can allow it with: /path/to/mcp-shell-tools/scripts/grant.sh
--state-dir /home/you/.mcp-shell-tools set --root /etc --for 1h

Deleted entries go to a trash in the state directory, not away for good.

Documentation

• Running the server: options, environment, authentication, reverse proxy, systemd
• Boundary and grants: modes, commands, grants
• Tool reference: all 33 tools with their parameters
• Using the library: workspace, errors, serving the catalogue from a server of your own
• Development: setup, checks, layout
• Changes

License

MIT, see LICENSE.