Skip to main content

docker-kestrel

An MCP server that provides diagnostic intelligence for Docker environments. No Prometheus, no Datadog — just the daemon and smart analysis.

Connect docker-kestrel to Claude Desktop, Claude Code, Cursor, or any MCP-compatible client and ask plain-English questions about your containers.

Why "kestrel"?

A kestrel is a small falcon known for hovering perfectly still in the wind while its eyes lock onto a target below. It watches — it doesn't swoop. docker-kestrel works the same way: it hovers over your containers and tells you exactly what's wrong, without touching anything.

What it does

Existing Docker MCP servers wrap CLI commands (start, stop, list). docker-kestrel reasons about what's going on:

  • diagnose_container — full diagnostic report: OOM detection, crash loop detection, health check analysis, resource snapshot, log summary
  • resource_overview — ranked resource usage across all containers with anomaly flags
  • network_map — Docker network topology, container IPs, port bindings
  • compose_drift — compare a docker-compose.yml against running containers to find drift
  • log_analysis — structured log analysis: error counts, pattern grouping, first/last occurrence

Quick start

# Install with uv
uv tool install docker-kestrel

# Or run directly without installing
uvx docker-kestrel

Claude Desktop — ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "docker-kestrel": {
      "command": "uvx",
      "args": ["docker-kestrel"]
    }
  }
}

Claude Code:

claude mcp add docker-kestrel uvx docker-kestrel

Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "docker-kestrel": {
      "command": "uvx",
      "args": ["docker-kestrel"]
    }
  }
}

Example queries

Once connected, you can ask your AI client:

  • "Why is my api container unhealthy?"
  • "Which container is using the most memory?"
  • "Why can't container A reach container B?"
  • "Has anything drifted from my docker-compose.yml?"
  • "Summarize the errors in the worker container's logs"

Development

git clone https://github.com/markalovell-git/docker-kestrel
cd docker-kestrel
uv sync --dev
uv pip install -e .

# Run unit tests (no Docker daemon required)
uv run pytest tests/test_analysis.py -v

# Run integration tests (requires Docker)
uv run pytest tests/test_integration.py -v

Requirements

  • Python 3.11+
  • Docker daemon running and accessible (via /var/run/docker.sock)

License

MIT

Metadata

Release files for docker-kestrel 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for docker-kestrel 0.1.0
File Size Uploaded Provenance Actions
docker_kestrel-0.1.0.tar.gz 75.9 kB Without provenance Details for docker_kestrel-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for docker-kestrel 0.1.0
File Interpreter ABI Platform Actions
docker_kestrel-0.1.0-py3-none-any.whl Python 3 none any Details for docker_kestrel-0.1.0-py3-none-any.whl

Total release size: 92.5 kB

Release files / docker_kestrel-0.1.0.tar.gz

Download URL docker_kestrel-0.1.0.tar.gz
Size 75.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e5cce8404d88293a4321a6f84674772fb1fe01a04327a817f9615386c0b5785d
BLAKE2b-256 checksum
How to use checksums
81a6b05078b775410be8fb079b8317d803ba04d17a4d825c0e5f0f0065d0e19b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / docker_kestrel-0.1.0-py3-none-any.whl

Download URL docker_kestrel-0.1.0-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
623b189a6959271f4966c04266e0d57327f4e37a1cd3429ec83033d4bfa9f1cf
BLAKE2b-256 checksum
How to use checksums
84d16337e38f04015d255bd02113259306340b64fea1c73734214b4189f1a3f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for docker-kestrel 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page