Metadata-Version: 2.4
Name: mcp-shell-tools
Version: 8.1.0
Summary: Workstation tools for AI assistants, as a Python library and an MCP server
Author-email: Ulrich Cuber <sonstige@uc-it.de>
License-Expression: MIT
Project-URL: Homepage, https://www.uc-it.de
Project-URL: Repository, https://github.com/cuber-it/mcp-shell-tools
Project-URL: Documentation, https://github.com/cuber-it/mcp-shell-tools/tree/master/doc
Project-URL: Changelog, https://github.com/cuber-it/mcp-shell-tools/blob/master/CHANGES.md
Keywords: mcp,model-context-protocol,shell,filesystem,tools,workstation,oauth
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Shells
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Provides-Extra: server
Requires-Dist: mcp<3,>=2; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: mcp<3,>=2; extra == "dev"
Dynamic: license-file

# 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.

```bash
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:

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

Over HTTP, with OAuth:

```bash
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:

```python
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:

```text
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](https://github.com/cuber-it/mcp-shell-tools/blob/master/doc/server.md):
  options, environment, authentication, reverse proxy, systemd
- [Boundary and grants](https://github.com/cuber-it/mcp-shell-tools/blob/master/doc/boundary.md):
  modes, commands, grants
- [Tool reference](https://github.com/cuber-it/mcp-shell-tools/blob/master/doc/tools.md):
  all 33 tools with their parameters
- [Using the library](https://github.com/cuber-it/mcp-shell-tools/blob/master/doc/library.md):
  workspace, errors, serving the catalogue from a server of your own
- [Development](https://github.com/cuber-it/mcp-shell-tools/blob/master/doc/development.md):
  setup, checks, layout
- [Changes](https://github.com/cuber-it/mcp-shell-tools/blob/master/CHANGES.md)

## License

MIT, see [LICENSE](https://github.com/cuber-it/mcp-shell-tools/blob/master/LICENSE).
