mcp-komodo

[![npm version](https://img.shields.io/npm/v/@samik081/mcp-komodo)](https://www.npmjs.com/package/@samik081/mcp-komodo)
[![Docker image](https://ghcr-badge.egpl.dev/samik081/mcp-komodo/latest_tag?trim=major&label=docker)](https://ghcr.io/samik081/mcp-komodo)
[![License: MIT](https://img.shields.io/npm/l/@samik081/mcp-komodo)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@samik081/mcp-komodo)](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

- **63 tools** across **14 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** -- lightweight native-fetch client, no SDK required
- **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) | 63 | Read, execute, and write -- full control |
| `read-execute` | 55 | Read and execute -- no resource creation/deletion, no user administration |
| `read-only` | 39 | Read only -- safe for exploration, no state changes |

**Tier details:**

- **full**: All 63 tools. Includes `komodo_write_resource` for creating, updating, and deleting Komodo resources, plus the user administration tools (service users, API keys, permissions).
- **read-execute**: 55 tools. All read tools plus execute tools (deploy, pull, lifecycle, run, etc.). The `komodo_write_resource` tool and the user administration write tools are hidden.
- **read-only**: 39 tools. List, get, logs, inspect, stats, summaries, operation history, and user/permission reads 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_SESSION_IDLE_TIMEOUT` | No | `1800` | Seconds of inactivity after which an HTTP session is closed and its memory released (sessions with a connected SSE stream are never closed). `0` disables. 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`, `users`, `write`

## Tools

mcp-komodo provides 63 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).

All 16 execute tools wait for the operation to complete and report its real outcome by default; pass `wait: false` for fire-and-forget, or `wait_timeout_seconds` to bound the wait (default 45s).

<details>
<summary>Servers (10 tools)</summary>

| 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 (`docker inspect` payload); env values render as `sha256:<12-hex>` digests unless `show_env_values: true` -- redaction covers `Env` arrays only, so labels, cmd, and mounts are returned unredacted | read-only | read-only, idempotent |
| `komodo_inspect_docker_image` | Inspect a Docker image (`docker image inspect` payload); baked-in env values render as `sha256:<12-hex>` digests unless `show_env_values: true` -- redaction covers `Env` arrays only, so labels, cmd, and layers are returned unredacted | 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 |

</details>

<details>
<summary>Stacks (10 tools)</summary>

| 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 (`docker inspect` payload); env values render as `s