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.

Related MCP server: TailOpsMCP

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