io.github.MP-Tool/komodo-mcp-server

Official

by MP-Tool · TypeScript

Komodo MCP Server

MCP server for Komodo - manage Docker containers, servers, stacks, and deployments via AI

Manage Docker containers, servers, stacks, and deployments through natural language.

README.md14 KBView on GitHub

🦎 Komodo MCP Server

Model Context Protocol Server for Komodo

Manage your Docker or Podman deployments through Komodo with AI assistants and automation tools.

Komodo MCP Server enables seamless interaction between AI assistants (like Claude, GitHub Copilot) and Komodo (Container Management Platform) for efficient container management, server orchestration, and deployment operations. The MCP-Server gives you the ability to control your Komodo-managed infrastructure by using natural language or automated workflows.

Features • Quick Start • Authentication • Documentation

</div>

Features

🛠️ Complete Infrastructure Control

70 Tools, 16 Categories — Full lifecycle management for containers, stacks, deployments, servers, builds, repos, procedures, actions, alerters, Docker Swarms (Komodo v2), variables, resource syncs and update history — from listing and inspecting to deploying, building, scaling and destroying.
Remote Terminal Access — Execute commands on servers, containers, deployments, and stack services with real-time output streaming, exit codes, and progress reporting.
Log Search & Analysis — Pattern-based log search across containers with configurable tail limits and match counting.

🔌 Deploy Anywhere

Multi-Transport — Streamable HTTP (stateful), HTTPS with TLS, legacy SSE, and stdio. Same server, any client.
Multi-Platform Docker — Production-ready images for amd64, arm64, arm/v7, and arm/v6 (Raspberry Pi). Non-root, multi-stage builds with tini init.
Works with Any MCP Client — Claude Desktop, VS Code / GitHub Copilot, or any MCP-compatible tool. Runs via Docker, npx, or native Node.js.

🔐 Security & Authentication

Three Auth Methods — API Key/Secret (recommended), username/password, or JWT token. All support Docker secrets via *_FILE variants.
Runtime Configuration — Set or change credentials dynamically via komodo_configure without restarting the server.
Hardened by Default — Input validation (Zod), secret scrubbing in logs, rate limiting, DNS rebinding protection, and security headers via Helmet.

⚡ Reliability & Operations

Live Progress & Cancellation — Long-running operations (deploy, start, stop) report real-time progress. Cancel any operation mid-flight via AbortSignal.
Auto-Reconnection — Connection monitoring with automatic recovery and exponential backoff. Auth failures stop retries immediately.
Health & Readiness — Kubernetes-ready /health and /ready endpoints. komodo_health_check reports server version, connectivity, and auth status.

Built on mcp-server-framework — a production-ready TypeScript MCP server framework with structured logging, OpenTelemetry, and session management.

Available Tools (70)

Category	Tools
Configuration	`komodo_configure`, `komodo_health_check`
Containers	`komodo_container_list`, `komodo_container_inspect`, `komodo_container_logs`, `komodo_container_search_logs`, `komodo_container_action` (start/stop/restart/pause/unpause)
Servers	`komodo_server_list`, `komodo_server_info`, `komodo_server_stats`, `komodo_server_apply` (create/update), `komodo_server_delete`, `komodo_server_action` (start_all/restart_all/pause_all/unpause_all/stop_all_containers, prune_, delete_network/image/volume)*
Stacks	`komodo_stack_list`, `komodo_stack_info`, `komodo_stack_apply` (create/update), `komodo_stack_delete`, `komodo_stack_action` (deploy/pull/start/restart/pause/unpause/stop/destroy)
Deployments	`komodo_deployment_list`, `komodo_deployment_info`, `komodo_deployment_apply` (create/update), `komodo_deployment_delete`, `komodo_deployment_action` (deploy/pull/start/restart/pause/unpause/stop/destroy)
Builds	`komodo_build_list`, `komodo_build_info`, `komodo_build_action` (run/cancel), `komodo_build_logs`, `komodo_build_apply` (create/update), `komodo_build_delete`
Repos	`komodo_repo_list`, `komodo_repo_info`, `komodo_repo_action` (clone/pull/build/cancel_build), `komodo_repo_apply` (create/update), `komodo_repo_delete`
Procedures	`komodo_procedure_list`, `komodo_procedure_info`, `komodo_procedure_action` (run), `komodo_procedure_apply` (create/update), `komodo_procedure_delete`
Actions	`komodo_action_list`, `komodo_action_info`, `komodo_action_action` (run/cancel), `komodo_action_apply` (create/update), `komodo_action_delete`
Alerters	`komodo_alerter_list`, `komodo_alerter_info`, `komodo_alerter_apply` (create/update), `komodo_alerter_delete`
Swarms	`komodo_swarm_list`, `komodo_swarm_info`, `komodo_swarm_apply` (create/update), `komodo_swarm_delete`, `komodo_swarm_nodes_list`, `komodo_swarm_services_list`, `komodo_swarm_action` (update_node/remove_nodes/remove_services/remove_stacks)
Resource Syncs	`komodo_resource_sync_list`, `komodo_resource_sync_info`, `komodo_resource_sync_action` (run/refresh), `komodo_resource_sync_apply` (create/update), `komodo_resource_sync_delete`
Variables	`komodo_variable_list`, `komodo_variable_info`, `komodo_variable_apply` (create/update — value/description/is_secret), `komodo_variable_delete`
Updates	`komodo_update_list` (filterable, paginated), `komodo_update_info`
Terminal	`komodo_exec` (target: server / container / deployment / stack_service)
API Keys	`komodo_user_list_api_keys`, `komodo_user_create_api_key`, `komodo_user_delete_api_key`

Tip: Every tool carries _meta.category (one of config, container, server, stack, deployment, build, repo, procedure, action, alerter, swarm, resource-sync, variable, update, terminal, user) and a requiredScopes array (komodo:read / komodo:operate / komodo:admin), so MCP clients and gateways can filter or gate tools by category and three-tier RBAC.

List/info/logs tools support cursor pagination via { cursor, page_size } (1–100, default 50) and emit _meta.page.next_cursor when more items are available. inspect, info, logs, and search_logs responses also include a session-scoped ephemeral://… resource link so large payloads can be fetched out-of-band via resources/read; pass inline_full: true to force inlining.

Quick Start

Docker Compose (Recommended for HTTP)

Deploy as a persistent HTTP server — connect from any MCP client.

bash

mkdir komodo-mcp && cd komodo-mcp
curl -O https://raw.githubusercontent.com/MP-Tool/komodo-mcp-server/main/docker/compose.yaml
curl -O https://raw.githubusercontent.com/MP-Tool/komodo-mcp-server/main/docker/docker.env
cp docker.env .env  # Edit with your credentials
docker compose up -d

→ Full Docker Guide

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config):

json

"komodo-mcp-server": {
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "KOMODO_URL=https://komodo.example.com:9120",
    "-e", "KOMODO_API_KEY=api-key",
    "-e", "KOMODO_API_SECRET=api-secret",
    "ghcr.io/mp-tool/komodo-mcp-server:latest"
  ]
}

→ Full Claude Guide

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

json

{
  "servers": {
    "Komodo MCP Server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "KOMODO_URL=https://komodo.example.com:9120",
        "-e", "KOMODO_API_KEY=api-key",
        "-e", "KOMODO_API_SECRET=api-secret",
        "ghcr.io/mp-tool/komodo-mcp-server:latest"
      ]
    }
  }
}

→ Full VS Code Guide · Node.js / npx (no Docker) · All Integrations

Use

Once connected, ask Claude, Copilot, or any MCP-compatible assistant:

code

"List all my Komodo servers"
"Show containers on production-server"  
"Start the nginx container"
"Deploy my-app to staging"
"Get stats for dev-server"

Testing with MCP Inspector

bash

npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp

Use /mcp for Streamable HTTP or /sse for legacy SSE transport (if enabled). Adjust host and port to match your setup.

Authentication

Three methods are supported — use whichever fits your setup:

Method	Environment Variables	Best For
API Key (recommended)	`KOMODO_API_KEY` + `KOMODO_API_SECRET`	Service accounts, automation
Username / Password	`KOMODO_USERNAME` + `KOMODO_PASSWORD`	Interactive users
JWT Token	`KOMODO_JWT_TOKEN`	Browser-based SSO (OIDC, GitHub, Google OAuth)

KOMODO_URL is always required. All credentials also support Docker secrets via *_FILE variants (e.g. KOMODO_API_KEY_FILE).

For the full configuration reference (env vars, config files, Docker secrets), see the Configuration Guide.

Disclaimer

AI tools (GitHub Copilot, Claude) are used as part of the development workflow — for code generation, architecture exploration, and documentation drafting. Every line of code and documentation is manually reviewed to ensure quality, correctness, and compliance with established engineering standards.

This software is provided under the GPL-3.0 License. If you find bugs or have ideas, issues and contributions are always welcome.

Contributing

Contributions are welcome! See our Contributing Guide for details.

Development

bash

# Clone and install
git clone https://github.com/MP-Tool/komodo-mcp-server.git
cd komodo-mcp-server
npm install

# Build and run
npm run build
npm start

Documentation

Guide	Description
Configuration	All environment variables, config file formats, priority chain, Docker secrets
Docker Deployment	Docker Compose setup, health checks, production deployment
Client Integrations	Claude Desktop, VS Code, Node.js/npx setup guides
Contributing	Development setup, coding standards, PR guidelines
Security	Vulnerability reporting, security best practices
Changelog	Version history and release notes

License

GPL-3.0 License - see LICENSE for details.

Requirements

Komodo v2.0.0 or later
Docker (for containerized deployment) or Node.js 22+ (for native installation)
Valid Komodo credentials (API Key/Secret, Username/Password, or JWT Token)

Security

Report security vulnerabilities via GitHub's Private Vulnerability Reporting (see SECURITY.md).

Best practices:

Never commit credentials
Use environment variables
Keep dependencies updated
Run as non-root user (default in Docker)

Install

Configuration

Environment variables

KOMODO_URLrequired

Komodo Core API URL

KOMODO_API_KEYsecret

API key for key-based authentication (recommended)

KOMODO_API_SECRETsecret

API secret for key-based authentication (recommended)

KOMODO_USERNAMEsecret

Username for login authentication (alternative to API key)

KOMODO_PASSWORDsecret

Password for login authentication (alternative to API key)

claude_desktop_config.json

{
  "mcpServers": {
    "komodo-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "komodo-mcp-server@1.4.1"
      ],
      "env": {
        "KOMODO_URL": "<YOUR_KOMODO_URL>",
        "KOMODO_API_KEY": "<YOUR_KOMODO_API_KEY>",
        "KOMODO_API_SECRET": "<YOUR_KOMODO_API_SECRET>",
        "KOMODO_USERNAME": "<YOUR_KOMODO_USERNAME>",
        "KOMODO_PASSWORD": "<YOUR_KOMODO_PASSWORD>"
      }
    }
  }
}

🦎 Komodo MCP Server

Features

🛠️ Complete Infrastructure Control

🔌 Deploy Anywhere

🔐 Security & Authentication

⚡ Reliability & Operations

Available Tools (70)

Quick Start

Docker Compose (Recommended for HTTP)

Claude Desktop

VS Code / GitHub Copilot

Use

Testing with MCP Inspector

Authentication

Disclaimer

Contributing

Development

Documentation

License

Requirements

Security

Links

Install

Configuration