MCP Ops Toolkit

中文说明 | English

A self-hosted Model Context Protocol (MCP) operations gateway for Linux control hosts. It provides a compact tool surface for safe filesystem and Git operations, authenticated HTTP transport, ChatGPT attachment upload, native file reading, SSH/SFTP adapters, and optional infrastructure integrations.

Security warning: this project can expose highly privileged operations. The unrestricted root-shell path is disabled by default. Audit the code, keep the service on loopback behind an authenticated reverse proxy or tunnel, use a dedicated Unix account, and allowlist every privileged bridge.

Highlights

• Compact FastMCP facade designed to keep tool discovery manageable.
• Constant-time Bearer or X-API-Key authentication for Streamable HTTP.
• Atomic binary attachment upload with size limits, SHA-256 verification, overwrite protection, and backup support.
• Native MCP text, image, and blob responses for local files.
• Structured filesystem, Git, Python, Node, and npm operations through a root-owned bridge.
• Persistent SSH sessions, argv-based remote execution, terminal I/O, and SFTP-style transfer through an external allowlisted bridge.
• Optional Azure, Cloudflare, control-plane, and encrypted secret-broker adapters.
• Optional full root shell with bounded runtime, bounded output files, output paging, and explicit opt-in.

Repository layout

• compact_app.py: the compact public MCP tool surface.
• http_server.py: authenticated Streamable HTTP entrypoint.
• mcp_main.py: stdio entrypoint.
• safe_ops.py / safe_ops_bridge.py: structured local operations.
• file_content.py: native MCP file responses.
• server.py: control-plane and optional root-shell implementation.
• azure_tools.py, cloudflare_tools.py, ssh_tools.py, secret_tools.py: optional bridge adapters.
• deploy/systemd/: generic systemd and sudoers examples.

Quick start

git clone https://github.com/gaojiefengxswhuhit/mcp-ops-toolkit.git
cd mcp-ops-toolkit
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
export MCP_OPS_ACCESS_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
python http_server.py

The default listener is 127.0.0.1:8792; /healthz is unauthenticated and all MCP routes require the access token. For stdio transport, run python mcp_main.py.

Privileged bridges

The MCP process should run as an unprivileged account. Privileged operations call narrowly named, root-owned executables under /usr/local/sbin/. The repository includes the safe-operations bridge and the optional root-shell bridge. Azure, Cloudflare, SSH, and secret-broker adapters define JSON or argv contracts, but their deployment-specific credential and host-resolution implementations are intentionally not included.

Expected bridge paths can be changed in source or wrapped with stable symlinks:

/usr/local/sbin/mcp-ops-toolkit-safe-ops
/usr/local/sbin/mcp-ops-toolkit-root-shell
/usr/local/sbin/mcp-ops-toolkit-azure-cli
/usr/local/sbin/mcp-ops-toolkit-cloudflare
/usr/local/sbin/mcp-ops-toolkit-ssh-bridge
/usr/local/sbin/mcp-ops-toolkit-secret-broker

Security defaults

• The HTTP server binds to loopback by default.
• DNS-rebinding protection is enabled.
• Allowed hosts and origins are configured through environment variables.
• Full root shell is disabled unless MCP_OPS_ENABLE_FULL_SHELL=1.
• File reads use allowlisted roots and deny common key and secret locations.
• Uploaded files are copied atomically and verified after the copy.
• Real tokens, host aliases, private domains, account identifiers, and credentials must stay outside Git.

See SECURITY.md before production use.

Tests

python -m compileall -q .
python test_server_contract.py server.py
python test_compact_contract.py .

License

MIT