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 summaryresource_overview— ranked resource usage across all containers with anomaly flagsnetwork_map— Docker network topology, container IPs, port bindingscompose_drift— compare adocker-compose.ymlagainst running containers to find driftlog_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.