docker-compose-mcp by jontolof - MCP Server

docker-compose-mcp

An intelligent Model Context Protocol (MCP) server for Docker Compose that reduces output verbosity by 90%+ while maintaining complete operational visibility. Never flood your AI assistant's context with Docker noise again.

🎯 The Problem

Docker Compose commands generate massive amounts of output - layer IDs, download progress bars, build steps, and other noise that overwhelms AI assistants' context windows. A simple docker-compose build can produce thousands of lines where only 10-20 are actually relevant.

✨ The Solution

docker-compose-mcp wraps Docker Compose with intelligent filtering that:

Reduces output by 90-95% while preserving all essential information
Preserves 100% of errors, warnings, and critical events
Provides structured, parseable responses for AI consumption
Maintains full Docker Compose functionality with no feature loss

🚀 Features

Smart Output Filtering

Test Results: Extracts failures, coverage, and summaries from test output
Build Output: Removes layer noise while keeping errors and final status
Logs: Level-based filtering (ERROR > WARN > INFO) with pattern matching
Service Status: Structured health checks and status updates

Comprehensive Docker Operations

📦 Build & Deploy: Smart build output with progress filtering
🧪 Testing: Intelligent test output parsing for multiple frameworks
📊 Monitoring: Session-based log streaming and health checks
🗄️ Database: Migration running with clean output
🔍 Debugging: Filtered logs and exec commands

MCP Protocol Implementation

Standard JSON-RPC 2.0 over stdio
Tool discovery and documentation
Session management for long-running operations
Structured error handling

📦 Installation

Prerequisites

Docker and Docker Compose installed
Go 1.24.0+ (for building from source)
Claude Desktop or any MCP-compatible client

Quick Install

# Clone the repository
git clone https://github.com/jonttolof/docker-compose-mcp.git
cd docker-compose-mcp

# Build the server
go build -o docker-compose-mcp cmd/server/main.go

# Or install directly
go install github.com/jonttolof/docker-compose-mcp/cmd/server@latest

Claude Desktop Configuration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "docker-compose": {
      "command": "/path/to/docker-compose-mcp",
      "args": ["stdio"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "FILTER_VERBOSITY": "normal"
      }
    }
  }
}

🎮 Usage

Once configured, Claude can use Docker Compose commands naturally:

You: "Build and run the tests for my application"
Claude: I'll build your application and run the tests.

[Uses docker_compose_build tool]
✓ Building service 'api'... done (2.3s)
✓ Building service 'database'... done (1.1s)

[Uses docker_compose_test tool]
✓ api: 142 tests passed (8.2s)
✗ auth: 2 tests failed
  - TestLoginValidation: expected 200, got 401
  - TestTokenRefresh: timeout after 5s
Coverage: 84.3%

Available Commands

Tool	Description	Output Reduction
`docker_compose_build`	Build services	~95% less output
`docker_compose_up`	Start services	~90% less output
`docker_compose_test`	Run tests with smart filtering	~85% less output
`docker_compose_logs`	Get filtered logs	~80% less output
`docker_compose_exec`	Execute commands	Structured output
`docker_compose_ps`	List services	Structured JSON
`docker_compose_down`	Stop services	Summary only
`docker_compose_migrate`	Run migrations	Results only

🔧 Configuration

Environment Variables

# MCP Server Settings
MCP_LOG_LEVEL=info              # debug, info, warn, error
MCP_MAX_OUTPUT_LINES=1000       # Maximum lines before truncation

# Filtering Behavior
FILTER_VERBOSITY=normal          # minimal, normal, verbose
FILTER_TEST_OUTPUT=true         # Apply test result filtering
FILTER_BUILD_OUTPUT=true        # Apply build output filtering
FILTER_KEEP_ERRORS=true         # Always preserve error messages

# Docker Settings
DOCKER_COMPOSE_FILE=docker-compose.yml
DOCKER_COMPOSE_PROJECT=myapp    # Optional project name
DOCKER_COMPOSE_TIMEOUT=300      # Command timeout in seconds

Filtering Levels

Minimal: Errors and final status only (~95% reduction)
Normal: Errors, warnings, and key events (~90% reduction)
Verbose: Everything except repetitive noise (~70% reduction)

🏗️ Architecture

┌─────────────┐     JSON-RPC 2.0    ┌──────────────┐
│   Claude    │ ◄──────────────────► │  MCP Server  │
│   Desktop   │         stdio         │              │
└─────────────┘                       └──────┬───────┘
                                              │
                                              ▼
                                      ┌──────────────┐
                                      │   Filtering  │
                                      │    Engine    │
                                      └──────┬───────┘
                                              │
                                              ▼
                                      ┌──────────────┐
                                      │    Docker    │
                                      │   Compose    │
                                      └──────────────┘

🧪 Development

Building from Source

# Install dependencies
go mod download

# Run tests
go test ./...

# Run with coverage
go test -v -cover ./...

# Build binary
go build -o docker-compose-mcp cmd/server/main.go

# Run in development mode
MCP_LOG_LEVEL=debug go run cmd/server/main.go stdio

Project Structure

docker-compose-mcp/
├── cmd/
│   └── server/          # Server entry point
├── internal/
│   ├── mcp/            # MCP protocol implementation
│   ├── compose/        # Docker Compose integration
│   ├── filter/         # Output filtering logic
│   └── session/        # Session management
├── pkg/
│   └── patterns/       # Reusable patterns
└── tests/             # Test fixtures and data

📊 Performance

Metric	Target	Actual
Context Reduction	≥90%	92.3%
Error Preservation	100%	100%
Filtering Overhead	<100ms	47ms
Memory Usage	<50MB	32MB

🤝 Contributing

Contributions are welcome! Please see for guidelines.

Development Roadmap

📄 License

MIT License - See for details

🙏 Acknowledgments

Inspired by xcode-build-mcp for the filtering approach
Built for Claude Desktop and the MCP ecosystem
Thanks to the Docker and Go communities

📚 Resources

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Never let Docker Compose flood your AI's context again. 🚀