Skip to main content
Glama
Vivekpatil200320

cyberrescue

by Vivekpatil200320
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

🐋 CyberRescue

Give Claude eyes and hands inside your broken Docker containers.

cyberrescue MCP server

📺 Live Triage Demonstration (33s)

https://github.com/user-attachments/assets/0ee0f583-b8c1-4abe-9dd4-4b59ec25fd49

Related MCP server: MCP Development Server

Overview

A locally-hosted MCP (Model Context Protocol) server that gives Claude real tools to debug Docker containers — fetch logs, inspect memory/CPU, and run diagnostic commands inside a container, all from a chat with Claude Desktop. Instead of writing bespoke glue code for every diagnostic endpoint you want an AI agent to reach (logs API, stats API, exec API, each with its own auth, sanitization, and error handling), CyberRescue exposes them once through MCP: register the server, and any MCP-capable client gets all three capabilities with validation, retry, and output caps already handled.

Results

  • Per-endpoint integration time cut from ~2 hours to under 30 minutes. Wiring an agent to a new container-diagnostic capability previously meant hand-rolling the client call, input validation, output truncation, and failure handling. With the MCP tool pattern established here (validate → semaphore-gated daemon call → retry with back-off → sanitized errors → capped output), adding an endpoint is a single decorated function.

  • 42 passing unit tests (30 for the core MCP server/security/retry logic, 12 for the public demo backend) covering input validation, command-safety blocklists, retry behavior, and the public-demo allowlist — run on every push via GitHub Actions CI.

  • Verified A-Grade Quality on Glama and listed on global MCP indexes.

Live Demo

(Link goes here once deployed — backend setup: infra/README.md; frontend: deploy web/ to Vercel with its root directory set to web/.) A public demo of the real tool running against 3 intentionally broken sandboxed containers (broken-flask, leaking-node, crashed-nginx). It's the same stream_container_logs / inspect_memory_dump / execute_isolated_script logic used by the local MCP server, exposed over a small FastAPI backend that's locked to those 3 containers with a fixed diagnostic-command menu (no arbitrary containers, no freeform shell input) — see SECURITY.md for the full threat model. The local MCP path (this README, below) and the public demo are two different deployment contexts sharing one core (src/cyberrescue/core.py).

Claude Desktop --stdio--> server.py ---\
                                        +--> core.py (docker calls) --> Docker daemon
   Vercel (Next.js) --HTTPS--> backend/app --/

What it does

CyberRescue exposes three tools to Claude:

  • stream_container_logs — fetch stdout/stderr logs from a container by ID or name (tail, since-timestamp, keyword filter; 50KB hard cap with truncation flag).

  • inspect_memory_dump — live CPU/memory snapshot via docker stats, plus top processes via ps aux --sort=-%mem.

  • execute_isolated_script — run a shell command inside a container via docker exec, with input validation, a command blocklist, and a hard asyncio timeout.

Everything runs locally over stdio — no network ports, no cloud service, no API keys beyond what you already use for Claude Desktop.

Architecture

flowchart LR
    A[Claude Desktop / MCP client] <-- "JSON-RPC over stdio" --> B[CyberRescue<br/>FastMCP server]
    B --> C{Security layer}
    C --> D["validate_container_id()"]
    C --> E["check_command_safety()<br/>command blocklist"]
    C --> F[Semaphore<br/>max 4 concurrent daemon calls]
    F --> G["Retry with exponential back-off<br/>(read-only calls: logs, stats)"]
    G --> H[(Docker daemon<br/>via python-on-whales)]
    H --> I[docker logs / docker stats / docker exec]
    B -- "sanitized errors, 50KB output cap" --> A

Read-only telemetry calls (logs, stats) retry up to 3 times with exponential back-off (0.5s → 1s) on transient daemon failures; docker exec is deliberately never retried, since it isn't idempotent. Raw Docker exceptions are logged server-side and never leaked to the client — they can contain host socket paths and usernames.

Requirements

Setup — macOS

1. System tools

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew install git
curl -LsSf https://astral.sh/uv/install.sh | sh
brew install --cask docker

Open Docker Desktop from Applications and let it finish starting (steady whale icon in the menu bar). Then install Claude Desktop from claude.ai → Download for Mac.

2. Clone and install

git clone https://github.com/vivekpatil200320/cyberrescue.git
cd cyberrescue
uv sync

3. Verify

uv run python -c "from cyberrescue.server import mcp; print('OK:', mcp.name)"
uv run pytest tests/ -v

4. Register with Claude Desktop

Find your uv path:

which uv

Edit (or create) ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cyberrescue": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": [
        "run",
        "--project",
        "/Users/YOUR_USERNAME/path/to/cyberrescue",
        "python",
        "-m",
        "cyberrescue.server"
      ]
    }
  }
}

If the file already has other mcpServers entries, merge "cyberrescue" in as an additional key rather than overwriting the file.

Fully quit Claude Desktop (Cmd+Q) and reopen it. Check the tools/slider icon near the message box — cyberrescue should appear with all three tools listed.

Setup — Windows (via WSL2)

WSL2 is the recommended path because Docker Desktop for Windows runs its Linux containers through it, and python-on-whales/docker exec behave most predictably there.

1. Install WSL2 and Ubuntu

In an Administrator PowerShell:

wsl --install

Restart if prompted, then open the new "Ubuntu" app from the Start menu and finish the Linux user setup.

2. Install Docker Desktop for Windows

Download from docker.com, install, and during setup enable "Use WSL 2 based engine". In Docker Desktop settings, under Resources → WSL Integration, enable integration with your Ubuntu distro.

3. Inside the WSL Ubuntu terminal — install tooling

sudo apt update
sudo apt install -y git python3 build-essential
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

4. Clone and install

git clone https://github.com/vivekpatil200320/cyberrescue.git
cd cyberrescue
uv sync

5. Verify

uv run python -c "from cyberrescue.server import mcp; print('OK:', mcp.name)"
uv run pytest tests/ -v
docker ps -a

(docker ps should work inside WSL once Docker Desktop's WSL integration is enabled.)

6. Install Claude Desktop (native Windows)

Download from claude.ai → Download for Windows, install normally (not inside WSL).

7. Register with Claude Desktop

Find your uv path inside WSL:

which uv

Edit %APPDATA%\Claude\claude_desktop_config.json (open via File Explorer: paste %APPDATA%\Claude into the address bar) and add an entry that runs the server through WSL:

{
  "mcpServers": {
    "cyberrescue": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "cd /home/YOUR_LINUX_USERNAME/cyberrescue && /home/YOUR_LINUX_USERNAME/.local/bin/uv run python -m cyberrescue.server"
      ]
    }
  }
}

Replace YOUR_LINUX_USERNAME and the path with your actual WSL username and clone location. Fully quit Claude Desktop and reopen it. Check the tools/slider icon — cyberrescue should appear with all three tools.

Usage

Ask Claude Desktop something like:

Debug the container named my-app: read the last 150 log lines, check its memory and CPU usage, and run printenv DATABASE_URL inside it.

Claude will call the three tools as needed and report back root cause and fix.

Demo containers

demo/ contains three intentionally broken images for testing:

  • broken_flask — crashes on startup with a missing-env-var KeyError

  • leaking_node — leaks ~10MB/sec until OOM-killed

  • crashed_nginx — fails to start due to invalid config syntax

docker build -t demo-broken-flask demo/broken_flask
docker build -t demo-leaking-node demo/leaking_node
docker build -t demo-crashed-nginx demo/crashed_nginx

These same 3 containers, run via infra/docker-compose.yml with fixed names (broken-flask, leaking-node, crashed-nginx), are what the public web demo above is sandboxed to — see src/cyberrescue/demo_policy.py.

Public web demo architecture

  • src/cyberrescue/core.py — the actual Docker-calling logic (logs/stats/exec), shared by both paths below.

  • src/cyberrescue/server.py — thin @mcp.tool() wrappers around core.py, served over stdio for Claude Desktop. Unchanged behavior from earlier versions.

  • src/cyberrescue/demo_policy.py — the allowlist (3 fixed container names) and fixed diagnostic-command menu used only by the public HTTP backend, never by the stdio tools.

  • backend/ — a FastAPI app (separate uv workspace member, own dependencies) that wraps core.py under the demo_policy restrictions, adds rate limiting, and an /narrate route that asks Claude to generate a root-cause explanation from already-captured evidence.

  • web/ — a Next.js/Tailwind frontend (deployed to Vercel) that talks to the backend.

  • infra/ — VPS deployment artifacts (docker-compose for the 3 demo containers, systemd units, Caddy config, a periodic reset job). See infra/README.md to stand it up.

Security

See SECURITY.md for the input validation, command blocklist, and concurrency/sanitization policy.

Future Enhancements

  • Standalone binary packaging (PyInstaller/Nuitka) for zero-Python-install distribution

  • Streaming log reads for very large logs (currently buffers full log before truncating)

  • Optional SQLite audit log for compliance use cases

  • Native (non-WSL) Windows support

License

MIT License

Copyright (c) 2026 Vivek Patil

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Available Tools

3 tools
execute_isolated_scriptA

Run a shell command string inside a container via docker exec.

Validates container_id and blocks known-dangerous command patterns
before running anything. Enforces a hard timeout via asyncio so a
runaway command can never hang the server.

Args:
    container_id: Container ID or name.
    command: Shell command string to run (executed via `sh -c`).
    timeout_seconds: Max seconds to wait before killing the command.

Returns:
    dict with stdout, stderr, exit_code, timed_out.
ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYes
commandYes
timeout_secondsNo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behaviors: validates container_id, blocks dangerous patterns, enforces a hard timeout via asyncio, and returns a dict with stdout, stderr, exit_code, timed_out. This informs the agent of safety and timeout guarantees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, starting with a clear purpose sentence followed by a bulleted Args and Returns list. Every sentence is informative and no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (3 parameters, no output schema, no annotations), the description is thorough: covers purpose, safety, timeout behavior, and return format. The agent has enough information to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description provides clear explanations for all three parameters: container_id is ID or name, command is executed via sh -c, timeout_seconds is max seconds before killing. This adds critical meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Run a shell command string') and the resource ('inside a container via docker exec'). It is distinct from sibling tools (inspect_memory_dump and stream_container_logs) which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for running shell commands but does not explicitly specify when to use this tool versus alternatives, nor does it mention when not to use it. No comparison to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_memory_dumpA

Return live memory and CPU stats, plus top processes, for a container.

Uses `docker stats --no-stream` for a point-in-time snapshot (this is not
a real heap dump — the name is aspirational). The container must be
running for stats to be available.

Args:
    container_id: Container ID or name.
    include_processes: If True, also runs `ps aux --sort=-%mem` inside
        the container and includes the output.

Returns:
    dict with cpu_percent, memory_mb, memory_limit_mb, memory_percent,
    and optionally processes (list of strings, one per ps line).
ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYes
include_processesNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explains the non-destructive nature, the use of docker stats, and the optional inclusion of process list. It does not disclose permissions or rate limits, but for a read-only tool this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a short summary, then usage notes, then a structured Args section, and finally Returns. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only 2 parameters, no output schema, and no annotations, the description is quite complete. It covers inputs, outputs, and behavioral details. Could mention error handling for non-running containers, but that's minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameters. It clearly describes 'container_id' as the container ID or name, and 'include_processes' with its effect (runs ps aux). This fully compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns live memory, CPU stats, and top processes for a container. The verb 'inspect' combined with the resource 'memory_dump' is apt, and the description distinguishes this tool from siblings like 'execute_isolated_script' and 'stream_container_logs'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes the container must be running and that it uses a point-in-time snapshot. It also clarifies that it's not a real heap dump, which prevents misuse. However, it does not explicitly state when to use this tool vs the siblings, though the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stream_container_logsA

Fetch stdout/stderr logs from a Docker container by ID or name.

Args:
    container_id: Container ID or name.
    tail: Number of lines to fetch from the end of the logs.
    since: Optional ISO 8601 timestamp; only return logs after this time.
    filter_keyword: Optional substring; only return lines containing it.

Returns:
    dict with container_id, log_lines, line_count, truncated.
ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYes
tailNo
sinceNo
filter_keywordNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It clearly explains the parameters and the return value, implying a read-only operation ('fetch'). It could explicitly state that the tool does not modify state, but the information is sufficient for safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: a single purpose sentence, followed by well-structured Args and Returns sections. No wasted words, and the most important information (purpose) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema, the description provides a complete return structure (container_id, log_lines, line_count, truncated). All parameters are explained. The tool is simple and the description covers all necessary information for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the schema alone provides no parameter descriptions. The description fully compensates by explaining each parameter's purpose (container_id as ID or name, tail as number of lines, since as ISO timestamp, filter_keyword as substring). This adds essential meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch stdout/stderr logs from a Docker container by ID or name.' This clearly identifies the verb (fetch), the resource (logs), and the scope (by container ID/name). It is distinct from sibling tools which deal with scripts and memory dumps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use the tool (to fetch logs) and explains each parameter's role. However, it does not explicitly state when not to use it or provide alternatives, though siblings are sufficiently different that exclusion is implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedexecute_isolated_script
    • First observedinspect_memory_dump
    • First observedstream_container_logs
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct purpose: running commands, inspecting memory/CPU, and fetching logs. There is no overlap, making it easy for an agent to differentiate and select the appropriate tool.

Naming Consistency4/5

All tool names use snake_case and follow a verb_noun pattern, though the noun phrases vary in structure (e.g., 'isolated_script' vs 'memory_dump'). This is mostly consistent and readable.

Tool Count4/5

Three tools is slightly minimal but appropriate for a focused container debugging/rescue server. The tools cover execution, resource inspection, and logs, which are core needs.

Completeness3/5

The server covers essential container debugging actions but lacks listing containers, file copying, or lifecycle management. This may limit its usefulness in broader rescue scenarios.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Vivekpatil200320/cyberrescue'

If you have feedback or need assistance with the MCP directory API, please join our Discord server