BuzzbeeSCD/komodo-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e7a85e52d4c25893f04b84a05777dc8ff4ee467
komodo-mcp-server/README.md
T
bot-hermes 2402b3b7fa feat: full Komodo API coverage — 11 tools, ~336 endpoints 
Expand from 7 tools to 11 tools covering 100% of the Komodo v2.3.2 API:

New tools:
- komodo_summary: resource summaries/stats
- komodo_inspect: Docker object inspection (16 types)
- komodo_search_logs: log search with query
- komodo_list_detail: extended listing (27 types)

Expanded existing tools:
- 12 → 21 resource types (action, repo, builder, swarm, variable, user_group, alert, terminal, git_provider_account)
- 37 → 100+ execute operations
- komodo_logs: 4 resource types with proper endpoints

Other changes:
- API key auth support (X-Api-Key / X-Api-Secret headers)
- 30s fetch timeout + structured error handling
- Updated docs: references/api.md (483 lines), README.md (238 lines)
2026-09-07 21:10:19 +00:00

239 lines
8.9 KiB
Markdown
Raw Blame History

# Komodo MCP Server
MCP server for the [Komodo](https://komo.do) build/deploy platform. Exposes 11 tools that map to Komodo's full RPC API surface (~336 endpoints) via the Model Context Protocol.
## Setup
### Prerequisites
- Node.js 22+
- A running Komodo instance with API access
### Authentication
The server supports two authentication methods:
**API Key (Preferred):**
| Variable | Required | Description |
|----------|----------|-------------|
| `KOMODO_BASE_URL` | Yes | Base URL of your Komodo instance |
| `KOMODO_API_KEY` | Yes | API key from Komodo UI Settings |
| `KOMODO_API_SECRET` | Yes | API secret from Komodo UI Settings |
**JWT Login:**
| Variable | Required | Description |
|----------|----------|-------------|
| `KOMODO_BASE_URL` | Yes | Base URL of your Komodo instance |
| `KOMODO_USERNAME` | Yes | Komodo login username |
| `KOMODO_PASSWORD` | Yes | Komodo login password |
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | No | `9800` | Port for the HTTP/SSE transport |
`KOMODO_URL` is accepted as a legacy alias for `KOMODO_BASE_URL`.
### Install & Build
```bash
npm install
npm run build
```
### Run
```bash
npm start
```
Or for development with live reload:
```bash
npm run dev
```
The server starts on `http://0.0.0.0:9800/mcp` with a health check at `/health`.
### MCP Client Configuration
Add to your MCP client config (e.g. `mcp.json` or equivalent):
```json
{
"mcpServers": {
"komodo": {
"url": "http://localhost:9800/mcp"
}
}
}
```
## Tools
### `komodo_list`
List or search Komodo resources.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | Resource type (see below) |
| `search` | string | No | Search query — uses Search* endpoint instead of List* |
| `project` | string | No | Filter by project name or ID |
Returns a JSON array of matching resources.
### `komodo_get`
Get a single resource by ID or name.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | Resource type |
| `id` | string | Yes | Resource ID or name |
### `komodo_create`
Create a new resource.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | Resource type |
| `params` | object | No | Fields for the corresponding Create* endpoint |
### `komodo_update`
Update an existing resource by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | Resource type |
| `id` | string | Yes | Resource ID or name |
| `params` | object | No | Fields to update |
### `komodo_delete`
Delete a resource by ID or name.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | Resource type |
| `id` | string | Yes | Resource ID or name |
### `komodo_execute`
Execute a Komodo operation. 100+ operations available.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `operation` | enum | Yes | Operation to run |
| `id` | string | No | Resource ID or name |
| `params` | object | No | Additional operation parameters |
**Operations (100+):**
| Category | Operations |
|----------|------------|
| Build & Deploy | `run_build`, `deploy_stack`, `deploy_stack_service`, `deploy`, `deploy_stack_if_changed`, `destroy_stack`, `destroy_container`, `destroy_deployment` |
| Repo | `build_repo`, `clone_repo`, `pull_repo`, `pull_deployment`, `cancel_repo_build`, `clear_repo_cache` |
| Procedure & Action | `run_procedure`, `run_procedure_stage`, `run_action`, `cancel_action`, `cancel_build`, `cancel_procedure` |
| Stack | `run_stack_refresh_cache`, `run_stack_refresh_content`, `run_stack_pull`, `run_stack_pull_deployment`, `run_stack_stop`, `run_stack_restart`, `run_stack_pause`, `run_stack_unpause`, `run_stack_remove_orphan_containers`, `run_stack_toggle_service_dependencies`, `run_stack_auto_update`, `run_stack_commit`, `start_stack`, `run_resource_sync`, `run_sync_deployment` |
| Container Lifecycle | `start_container`, `stop_container`, `restart_container`, `pause_container`, `unpause_container`, `start_all_containers`, `stop_all_containers`, `restart_all_containers`, `pause_all_containers`, `unpause_all_containers` |
| Deployment Lifecycle | `start_deployment`, `stop_deployment`, `restart_deployment`, `pause_deployment`, `unpause_deployment` |
| Server | `run_server_refresh`, `run_server_refresh_containers`, `run_server_update_periphery`, `run_server_prune_images`, `run_server_prune_containers`, `run_server_prune_networks`, `run_server_stats`, `run_server_run_command`, `run_server_scripts`, `run_server_copy`, `run_server_move`, `rotate_all_server_keys` |
| Docker Cleanup | `prune_buildx`, `prune_docker_builders`, `prune_system`, `prune_volumes`, `delete_image`, `delete_network`, `delete_volume` |
| Swarm | `remove_swarm_nodes`, `remove_swarm_services`, `remove_swarm_configs`, `remove_swarm_secrets`, `remove_swarm_stacks`, `create_swarm_config`, `create_swarm_secret`, `rotate_swarm_config`, `rotate_swarm_secret`, `update_swarm_node` |
| Batch | `batch_run_build`, `batch_deploy_stack`, `batch_deploy_stack_if_changed`, `batch_deploy`, `batch_pull_stack`, `batch_pull_repo`, `batch_build_repo`, `batch_clone_repo`, `batch_run_procedure`, `batch_run_action`, `batch_destroy_deployment`, `batch_destroy_stack` |
| Admin | `global_auto_update`, `backup_core_database`, `rotate_core_keys`, `send_alert`, `test_alerter`, `sleep`, `get_mcp_token` |
### `komodo_logs`
Get logs for a deployment, stack, container, or swarm service.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | `deployment`, `stack`, `container`, or `swarm_service` |
| `id` | string | Yes | Resource ID or name |
| `tail` | number | No | Number of recent log lines |
### `komodo_summary`
Get summary stats for a resource type.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | `build`, `deployment`, `server`, `stack`, `alerter`, `procedure`, `sync_resource`, `repo`, `builder`, `swarm`, `action` |
### `komodo_inspect`
Inspect a Docker object.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `inspect_type` | enum | Yes | `container`, `image`, `network`, `volume`, `swarm`, `swarm_node`, etc. |
| `id` | string | Yes | Object ID or name |
| `server` | string | No | Server name (for server-scoped objects) |
### `komodo_search_logs`
Search logs with a query string.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resource_type` | enum | Yes | `container`, `deployment`, `stack`, `swarm_service` |
| `id` | string | Yes | Resource ID or name |
| `query` | string | Yes | Search query to filter log lines |
| `tail` | number | No | Number of recent log lines |
### `komodo_list_detail`
Extended listing for specific Docker/infrastructure objects.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `list_type` | enum | Yes | What to list (see below) |
| `server` | string | No | Server name filter |
| `pattern` | string | No | Filter pattern |
**List types:** `containers`, `all_containers`, `images`, `networks`, `volumes`, `system_processes`, `schedules`, `permissions`, `api_keys`, `secrets`, `updates`, `build_versions`, `compose_projects`, `full_stacks`, `full_builds`, `full_servers`, `full_deployments`, `full_procedures`, `full_repos`, `full_builders`, `full_swarms`, `full_actions`, `full_alerters`, `full_resource_syncs`
## Resource Types
All tools that accept `resource_type` support these values:
| Value | Komodo Resource |
|-------|----------------|
| `stack` | Docker Compose stacks |
| `build` | Build configurations |
| `server` | Managed servers |
| `procedure` | Automation procedures |
| `deployment` | Deployments |
| `alerter` | Alert configurations |
| `image_registry_account` | Container registry accounts |
| `sync_resource` | Sync resources |
| `user` | Users |
| `tag` | Tags |
| `execution` | Execution history |
| `access_request` | Access requests |
| `action` | Automation actions |
| `repo` | Git repositories |
| `builder` | Build configurations |
| `swarm` | Docker Swarm clusters |
| `variable` | Environment variables |
| `user_group` | Permission groups |
| `alert` | Alert history |
| `terminal` | Web terminals |
| `git_provider_account` | Git provider connections |
## Architecture
- **Transport:** HTTP/SSE via `StreamableHTTPServerTransport` (MCP protocol)
- **Auth:** API Key headers (preferred) or JWT login with auto-refresh
- **API:** Komodo RPC-style — all calls are `POST /{read|write|execute}/{RequestName}`
- **Coverage:** ~336 of ~336 Komodo API endpoints (100%)
## License
Private — BuzzbeeSCD
Reference in New Issue View Git Blame Copy Permalink