# mcp_shell_tools

A full-featured MCP server for local development — filesystem, shell, editor, session persistence.

Built as a practical companion to the blog series on [uc-it.de](https://uc-it.de) about building MCP servers from scratch. This is not a demo — it runs in daily production use with Claude Desktop, claude.ai, and ChatGPT.

## What Makes This Different

Most MCP servers offer a handful of tools over stdio. This one provides:

- **24 tools** across 7 categories (filesystem, editor, search, shell, project context, memory, sessions)
- **Two transports** — stdio for Claude Desktop, Streamable HTTP for remote clients
- **Session persistence** — memory and context survive across conversations
- **Security layer** — dangerous command patterns are blocked, sudo requires confirmation
- **Process isolation** — subprocesses run in separate process groups with timeout enforcement
- **OAuth 2.0** — optional authentication for remote access via Traefik reverse proxy

## Tools

| Category | Tools |
|----------|-------|
| Filesystem | `file_read`, `file_write`, `file_list`, `glob_search`, `file_delete`, `file_move`, `file_copy`, `file_append`, `tree` |
| Editor | `str_replace`, `diff_preview` |
| Search | `grep` |
| Shell | `shell_exec`, `env`, `set_env` |
| Project | `cd`, `cwd`, `project_init` |
| Memory | `memory_add`, `memory_show`, `memory_clear` |
| Session | `session_save`, `session_resume`, `session_list` |

## Quickstart

```bash
git clone https://github.com/cuber-it/mcp_shell_tools.git
cd mcp_shell_tools
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Claude Desktop (stdio)

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "shell-tools": {
      "command": "/path/to/mcp_shell_tools/run.sh"
    }
  }
}
```

Restart Claude Desktop. The tools are now available.

### Streamable HTTP (Remote)

```bash
python code/main.py serve --http 12201
```

This starts the server on port 12201 with the `/mcp` endpoint. For production use with OAuth, see the systemd service template in `mcp-shell-http.service`.

## How It Works

```
Claude Desktop ──► run.sh ──► mcp_shell_tools (stdio)

claude.ai / ChatGPT
      │
      ▼
  Reverse Proxy ──► host:12201 (/mcp)
      │
  OAuth Server  ──► host:9080
```

The server manages a working directory, environment variables, and session state. Tools operate relative to the current working directory (changeable via `cd`). Project context is loaded from `CLAUDE.md` files. Memory entries persist across tool calls within a session.

## Security

Shell commands pass through a security filter before execution:

- **Blocked patterns** — `rm -rf /`, `dd of=/dev/`, `mkfs`, fork bombs, etc.
- **Sudo warning** — requires explicit confirmation
- **Process groups** — each subprocess runs in its own session, enabling clean kills on timeout
- **Output truncation** — prevents context overflow from large outputs

See `code/config.py` for the full list of blocked patterns.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_HOST` | `127.0.0.1` | Bind address (HTTP mode) |
| `MCP_PORT` | `12201` | Port (HTTP mode) |
| `MCP_OAUTH_ENABLED` | `false` | Enable OAuth authentication |
| `MCP_OAUTH_SERVER_URL` | — | OAuth server URL |
| `MCP_PUBLIC_URL` | — | Public-facing server URL |

## Project Structure

```
mcp_shell_tools/
├── code/
│   ├── main.py              # CLI entry point (stdio / HTTP)
│   ├── server.py             # FastMCP setup, tool registration
│   ├── config.py             # Constants, security patterns
│   ├── state.py              # Working directory, env vars
│   ├── health_server.py      # HTTP health endpoint
│   ├── heinzel_integration.py # Optional registry integration
│   ├── tools/
│   │   ├── filesystem.py     # 9 file operations
│   │   ├── editor.py         # str_replace, diff_preview
│   │   ├── search.py         # grep with regex support
│   │   ├── shell.py          # Command execution with security
│   │   ├── project.py        # Working directory, CLAUDE.md
│   │   ├── memory.py         # Persistent notes and decisions
│   │   ├── session.py        # Save/resume sessions
│   │   └── commands.py       # Slash commands (/verbose, /log)
│   ├── persistence/
│   │   ├── models.py         # Data models (Session, Memory)
│   │   └── session_manager.py # JSON-based persistence
│   └── utils/
├── tests/                    # 70 tests
├── config/
│   └── traefik-mcp.yml      # Example Traefik config
├── docs/
│   ├── ARCHITECTURE.md
│   ├── HTTP_STABILITY.md
│   └── ROADMAP.md
└── mcp-shell-http.service    # Systemd service template
```

## Requirements

- Python 3.10+
- `mcp` SDK >= 1.26.0

## Further Reading

- [Blog: Building MCP Servers](https://uc-it.de) — the blog series this project accompanies
- [Model Context Protocol](https://modelcontextprotocol.io) — MCP specification
- `docs/ARCHITECTURE.md` — detailed code architecture
- `docs/HTTP_STABILITY.md` — transport evolution and Traefik setup
- `CHANGELOG.md` — version history

## License

MIT

## Author

UC IT Service — [uc-it.de](https://uc-it.de)

---

*Actively maintained and continuously evolving. Contributions and feedback welcome.*