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

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):

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

Restart Claude Desktop. The tools are now available.

Streamable HTTP (Remote)

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 — the blog series this project accompanies
• Model Context Protocol — 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

---

Actively maintained and continuously evolving. Contributions and feedback welcome.