Skip to main content
Glama

mcp-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

Related MCP server: git-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

License

MIT, see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers