MCP 服务器

mcp_shell_tools

A full-featured MCP server for local development with filesystem, shell, editor, session persistence, and security features.

README

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