# Mcp Komodo

> Manage Komodo through AI assistants

- **Type:** MCP server
- **Install:** `agentstack add mcp-samik081-mcp-komodo`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Samik081](https://agentstack.voostack.com/s/samik081)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.5.7
- **License:** MIT
- **Upstream author:** [Samik081](https://github.com/Samik081)
- **Source:** https://github.com/Samik081/mcp-komodo

## Install

```sh
agentstack add mcp-samik081-mcp-komodo
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://www.npmjs.com/package/@samik081/mcp-komodo)
[](https://ghcr.io/samik081/mcp-komodo)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)

# MCP Komodo

MCP server for the [Komodo](https://komo.do) DevOps platform. Manage servers, stacks, deployments, builds, and more through natural language in Cursor, Claude Code, and Claude Desktop.

## Features

- **53 tools** across **13 categories** covering the complete Komodo DevOps API
- **Three access tiers** (`read-only`, `read-execute`, `full`) for granular control
- **Category filtering** via `KOMODO_CATEGORIES` to expose only the tools you need
- **Zero HTTP dependencies** -- uses the official `komodo_client` SDK
- **Docker images** for `linux/amd64` and `linux/arm64` on [GHCR](https://ghcr.io/samik081/mcp-komodo)
- **Remote MCP** via HTTP transport (`MCP_TRANSPORT=http`) using the Streamable HTTP protocol
- **TypeScript/ESM** with full type safety

## API Compatibility

Built for Komodo **1.19.5**.

## Quick Start

Run the server directly with npx:

```bash
KOMODO_URL="https://komodo.example.com" \
KOMODO_API_KEY="your-api-key" \
KOMODO_API_SECRET="your-api-secret" \
npx -y @samik081/mcp-komodo
```

The server validates your Komodo connection on startup and fails immediately with a clear error if credentials are missing or invalid.

### Docker

Run with Docker (stdio transport, same as npx):

```bash
docker run --rm -i \
  -e KOMODO_URL=https://komodo.example.com \
  -e KOMODO_API_KEY=your-api-key \
  -e KOMODO_API_SECRET=your-api-secret \
  ghcr.io/samik081/mcp-komodo
```

To run as a remote MCP server with HTTP transport:

```bash
docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e KOMODO_URL=https://komodo.example.com \
  -e KOMODO_API_KEY=your-api-key \
  -e KOMODO_API_SECRET=your-api-secret \
  ghcr.io/samik081/mcp-komodo
```

The MCP endpoint is available at `http://localhost:3000` and a health check at `http://localhost:3000/health`.

## Configuration

**Claude Code CLI (recommended):**

```bash
# Using npx
claude mcp add --transport stdio komodo \
  --env KOMODO_URL=https://komodo.example.com \
  --env KOMODO_API_KEY=your-api-key \
  --env KOMODO_API_SECRET=your-api-secret \
  -- npx -y @samik081/mcp-komodo

# Using Docker
claude mcp add --transport stdio komodo \
  --env KOMODO_URL=https://komodo.example.com \
  --env KOMODO_API_KEY=your-api-key \
  --env KOMODO_API_SECRET=your-api-secret \
  -- docker run --rm -i ghcr.io/samik081/mcp-komodo

# Using remote HTTP (connect to a running Docker container or HTTP server)
claude mcp add --transport http komodo http://localhost:3000
```

**JSON config** (works with Claude Code `.mcp.json`, Claude Desktop `claude_desktop_config.json`, Cursor `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "komodo": {
      "command": "npx",
      "args": ["-y", "@samik081/mcp-komodo"],
      "env": {
        "KOMODO_URL": "https://komodo.example.com",
        "KOMODO_API_KEY": "your-api-key",
        "KOMODO_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

**Docker (stdio):**

```json
{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "KOMODO_URL=https://komodo.example.com",
        "-e", "KOMODO_API_KEY=your-api-key",
        "-e", "KOMODO_API_SECRET=your-api-secret",
        "ghcr.io/samik081/mcp-komodo"
      ]
    }
  }
}
```

**Remote MCP** (connect to a running Docker container or HTTP server):

```json
{
  "mcpServers": {
    "komodo": {
      "type": "streamable-http",
      "url": "http://localhost:3000"
    }
  }
}
```

## Access Tiers

Control which tools are available using the `KOMODO_ACCESS_TIER` environment variable:

| Tier | Tools | Description |
|------|-------|-------------|
| `full` (default) | 53 | Read, execute, and write -- full control |
| `read-execute` | 52 | Read and execute -- no resource creation/deletion via write tool |
| `read-only` | 36 | Read only -- safe for exploration, no state changes |

**Tier details:**

- **full**: All 53 tools. Includes `komodo_write_resource` for creating, updating, and deleting Komodo resources.
- **read-execute**: 52 tools. All read tools plus execute tools (deploy, pull, lifecycle, run, etc.). The `komodo_write_resource` tool is hidden.
- **read-only**: 36 tools. List, get, logs, inspect, stats, summaries, and operation history only. All execute and write tools are hidden.

Tools that are not available in your tier are not registered with the MCP server. They will not appear in your AI tool's tool list, keeping the context clean.

Set `KOMODO_ACCESS_TIER` to `read-only`, `read-execute`, or `full` (default: `full`).

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KOMODO_URL` | Yes | -- | URL of your Komodo Core instance |
| `KOMODO_API_KEY` | Yes | -- | API key for authentication |
| `KOMODO_API_SECRET` | Yes | -- | API secret for authentication |
| `KOMODO_ACCESS_TIER` | No | `full` | Access tier: `read-only`, `read-execute`, or `full` |
| `KOMODO_CATEGORIES` | No | *(all)* | Comma-separated category allowlist (e.g., `servers,stacks,builds`) |
| `KOMODO_TOOL_BLACKLIST` | No | *(none)* | Comma-separated list of tool names to exclude (e.g., `komodo_destroy_stack`) |
| `KOMODO_TOOL_WHITELIST` | No | *(none)* | Comma-separated list of tool names to force-include, bypassing access tier and category filters |
| `DEBUG` | No | `false` | Enable debug logging to stderr |
| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` (default) or `http` |
| `MCP_PORT` | No | `3000` | HTTP server port (only used when `MCP_TRANSPORT=http`) |
| `MCP_HOST` | No | `0.0.0.0` | HTTP server bind address (only used when `MCP_TRANSPORT=http`) |
| `MCP_EXCLUDE_TOOL_TITLES` | No | `false` | Set `true` to omit tool titles from registration (saves tokens) |

Generate API keys in the Komodo UI under **Settings > API Keys**.

### Available Categories

`servers`, `stacks`, `deployments`, `containers`, `builds`, `repos`, `procedures`, `actions`, `builders`, `alerters`, `resource-syncs`, `updates`, `write`

## Tools

mcp-komodo provides 53 tools organized by category. Each tool's Access column shows the minimum tier required: `read-only` (available in all tiers), `read-execute` (requires `read-execute` or `full`), or `full` (requires `full` tier only). The Hints column shows tool behavior: `read-only` (no state changes), `destructive` (modifies existing state), `idempotent` (same result if called twice).

Servers (10 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_servers` | List all servers with status and region | read-only | read-only, idempotent |
| `komodo_get_server` | Get server configuration, status, and action state | read-only | read-only, idempotent |
| `komodo_get_server_stats` | Get CPU, memory, disk usage, and load averages | read-only | read-only, idempotent |
| `komodo_get_server_info` | Get OS details, hardware info, and running processes | read-only | read-only, idempotent |
| `komodo_inspect_docker_container` | Inspect a Docker container (equivalent to docker inspect) | read-only | read-only, idempotent |
| `komodo_inspect_docker_image` | Inspect a Docker image (equivalent to docker image inspect) | read-only | read-only, idempotent |
| `komodo_inspect_docker_network` | Inspect a Docker network (equivalent to docker network inspect) | read-only | read-only, idempotent |
| `komodo_inspect_docker_volume` | Inspect a Docker volume (equivalent to docker volume inspect) | read-only | read-only, idempotent |
| `komodo_prune_docker` | Prune unused Docker resources on a server | read-execute | destructive, idempotent |
| `komodo_delete_docker_resource` | Delete a specific Docker image, volume, or network | read-execute | destructive |

Stacks (10 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_stacks` | List all stacks with state, server, and service count | read-only | read-only, idempotent |
| `komodo_get_stack` | Get stack configuration, services, and action state | read-only | read-only, idempotent |
| `komodo_list_stack_services` | List services in a stack with image, container state, and update availability | read-only | read-only, idempotent |
| `komodo_get_stacks_summary` | Get aggregate counts of all stacks by state | read-only | read-only, idempotent |
| `komodo_get_stack_log` | Get logs from stack services, with optional search | read-only | read-only, idempotent |
| `komodo_inspect_stack_container` | Inspect a container for a specific service in a stack | read-only | read-only, idempotent |
| `komodo_deploy_stack` | Deploy or redeploy a stack | read-execute | destructive |
| `komodo_pull_stack` | Pull latest images without redeploying (docker compose pull) | read-execute | idempotent |
| `komodo_stack_lifecycle` | Start, stop, restart, pause, or unpause a stack | read-execute | destructive |
| `komodo_destroy_stack` | Permanently destroy a stack | read-execute | destructive |

Deployments (9 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_deployments` | List all deployments with state, image, and server | read-only | read-only, idempotent |
| `komodo_get_deployment` | Get deployment configuration, container status, and action state | read-only | read-only, idempotent |
| `komodo_get_deployments_summary` | Get aggregate counts of all deployments by state | read-only | read-only, idempotent |
| `komodo_get_deployment_log` | Get container logs, with optional search | read-only | read-only, idempotent |
| `komodo_inspect_deployment_container` | Inspect the container for a deployment (equivalent to docker inspect) | read-only | read-only, idempotent |
| `komodo_deploy_deployment` | Deploy with latest image and configuration | read-execute | destructive |
| `komodo_pull_deployment` | Pull latest image without redeploying (docker pull) | read-execute | idempotent |
| `komodo_deployment_lifecycle` | Start, stop, restart, pause, or unpause a deployment | read-execute | destructive |
| `komodo_destroy_deployment` | Permanently destroy a deployment | read-execute | destructive |

Containers (1 tool)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_get_container_log` | Get logs from any Docker container on a server | read-only | read-only, idempotent |

Builds (4 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_builds` | List all build configurations with version info | read-only | read-only, idempotent |
| `komodo_get_build` | Get build configuration, builder, and action state | read-only | read-only, idempotent |
| `komodo_run_build` | Run a build to create a Docker image | read-execute | — |
| `komodo_cancel_build` | Cancel a running build | read-execute | destructive, idempotent |

Repos (3 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_repos` | List all repos with URL, server, and state | read-only | read-only, idempotent |
| `komodo_get_repo` | Get repo configuration, branch, and action state | read-only | read-only, idempotent |
| `komodo_repo_clone_pull` | Clone or pull a repo on its target server | read-execute | destructive |

Procedures (3 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_procedures` | List all procedures with state | read-only | read-only, idempotent |
| `komodo_get_procedure` | Get procedure stages, operations, and action state | read-only | read-only, idempotent |
| `komodo_run_procedure` | Run a procedure (executes all stages) | read-execute | destructive |

Actions (3 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_actions` | List all actions with state | read-only | read-only, idempotent |
| `komodo_get_action` | Get action configuration and action state | read-only | read-only, idempotent |
| `komodo_run_action` | Run a custom TypeScript/Deno action | read-execute | destructive |

Builders (2 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_builders` | List all builders with type | read-only | read-only, idempotent |
| `komodo_get_builder` | Get builder type, server configuration, and state | read-only | read-only, idempotent |

Alerters (2 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_alerters` | List all alerters with type | read-only | read-only, idempotent |
| `komodo_get_alerter` | Get alerter endpoint type, configuration, and status | read-only | read-only, idempotent |

Resource Syncs (3 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_resource_syncs` | List all resource syncs with state and repo info | read-only | read-only, idempotent |
| `komodo_get_resource_sync` | Get sync configuration, managed resources, and state | read-only | read-only, idempotent |
| `komodo_trigger_sync` | Trigger a GitOps sync from the Git repo | read-execute | destructive |

Updates (2 tools)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_list_updates` | List operation history with filters for resource type, target, operation, and success | read-only | read-only, idempotent |
| `komodo_get_update` | Get full operation details including logs with stdout/stderr for each stage | read-only | read-only, idempotent |

Write (1 tool)

| Tool | Description | Access | Hints |
|------|-------------|--------|-------|
| `komodo_write_resource` | Create, update, or delete any Komodo resource | full | destructive |

## Verify It Works

After configuring your MCP client, ask your AI assistant:

> "What servers are connected to Komodo?"

If the connection is working, the assistant will call `komodo_list_servers` and return your servers with their current state and region.

## Usage Examples

Once configured, ask your AI tool questions in natural language:

- **"List all my servers and their status"** -- calls `komodo_list_servers` to show every server with its current state and region.

- **"What's the CPU and memory usage on server prod-01?"** -- calls `komodo_get_server_stats` to show real-time resource utilization.

- **"Show me the logs from the production stack"** -- calls `komodo_get_stack_log` to retrieve recent log output from all services in the stack.

- **"Deploy the frontend stack"** -- calls `komodo_deploy_stack` to redeploy the stack with its current configuration.

- **"Why did the frontend stack deploy fail?"** -- calls `komodo_list_updates` to find the failed deploy, then `komodo_get_update` to show the full logs with stdout/stderr.

- **"Pull the latest images for the monitoring stack"** -- calls `komodo_pull_stack` to download updated images without redeploying.

- **"Create a new deployment called api-staging with image myapp:latest"** -- calls `komodo_write_resource` to create a new Deployment resource in Komodo.

## Troubleshooting

### Connection refused

Check that `KOMODO_URL` is correct and that Komodo Core is reachable from where the MCP server is running. The server validates the connection on startup, so if it started successfully, the URL was valid at that time.

### Invalid credentials / 401 Unauthorized

Verify your API key and secret are correct. Check that the key has not been revoked or expired in the Komodo UI under Settings > API Keys.

### Tools not showing up

Check your access tier setting. In `read-only` mode, only 36 tools are registered. In `read-execute` mode, 52 tools are registered. Use `full` (or omit `KOMODO_ACCESS_TIER`) for all 53 tools. Check `KOMODO_CATEGORIES` -- only tools in listed categories are registered. Also verify the server started without errors by checking stderr output.

## Development

```bash
# Inst

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Samik081](https://github.com/Samik081)
- **Source:** [Samik081/mcp-komodo](https://github.com/Samik081/mcp-komodo)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.5.7 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.5.7** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-samik081-mcp-komodo
- Seller: https://agentstack.voostack.com/s/samik081
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.