# Komodo MCP Server - Usage Guide
Complete guide to using the Komodo MCP server with Claude.
## Table of Contents
1. [Quick Start](#quick-start)
2. [Authentication](#authentication)
3. [Module Overview](#module-overview)
4. [Read Module](#read-module)
5. [Execute Module](#execute-module)
6. [Common Patterns](#common-patterns)
7. [Error Handling](#error-handling)
8. [Best Practices](#best-practices)
---
## Quick Start
### Installation
```bash
# Clone or download the repository
git clone https://github.com/your-org/komodo-mcp.git
cd komodo-mcp
# Install dependencies
npm install
# Build the server
npm run build
```
### Configuration
Create a `.env` file with your Komodo credentials:
```bash
KOMODO_URL=https://your-komodo-instance.com
KOMODO_API_KEY=your-api-key
KOMODO_API_SECRET=your-api-secret
```
### Add to Claude
Add the server to your Claude configuration:
```json
{
"mcpServers": {
"komodo": {
"command": "node",
"args": ["C:/path/to/komodo-mcp/dist/index.js"],
"env": {
"KOMODO_URL": "https://your-komodo-instance.com",
"KOMODO_API_KEY": "your-api-key",
"KOMODO_API_SECRET": "your-api-secret"
}
}
}
}
```
### First Request
Ask Claude:
```
List all my Komodo servers
```
Claude will use the `komodo_read_ListServers` tool to fetch your servers.
---
## Authentication
The Komodo MCP server handles authentication automatically using HMAC-based signing.
### How It Works
1. **API Key**: Identifies your application
2. **API Secret**: Signs requests with HMAC-SHA256
3. **Timestamp**: Included to prevent replay attacks
### Request Signing
Each request includes these headers:
```
X-Komodo-Api-Key: your-api-key
X-Komodo-Timestamp: 1234567890
X-Komodo-Signature: <HMAC-SHA256 signature>
```
The signature is calculated as:
```
HMAC-SHA256(METHOD + ENDPOINT + BODY + TIMESTAMP, API_SECRET)
```
### No Manual Auth Required
You don't need to handle authentication when using the MCP server. Just configure your credentials once, and the server handles all signing automatically.
---
## Module Overview
The Komodo MCP server exposes 60 tools across 6 modules:
| Module | Tools | Purpose | Examples |
|--------|-------|---------|----------|
| **Read** | 16 | Read-only data retrieval | List servers, get deployment info |
| **Execute** | 9 | Trigger actions | Deploy apps, start/stop servers |
Additional modules (planned):
- **Auth** (4 tools): Login, logout, token refresh
- **User** (6 tools): User management
- **Write** (21 tools): Create/update/delete resources
- **Terminal** (4 tools): SSH terminal access
---
## Read Module
The read module provides read-only access to all Komodo resources. All read operations are safe and idempotent.
### Servers
#### List Servers
**Tool**: `komodo_read_ListServers`
List all servers with optional filtering.
**Example**:
```
Show me all running servers
```
**Parameters**:
- `page` (optional): Page number for pagination (default: 1)
- `page_size` (optional): Items per page (default: 50)
- `status` (optional): Filter by status (running, stopped, pending, error)
**Response**:
```json
{
"items": [
{
"id": "srv_123abc",
"name": "production-api",
"host": "192.168.1.100",
"port": 8080,
"status": "running",
"tags": ["production", "api"],
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-26T14:20:00Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
#### Get Server
**Tool**: `komodo_read_GetServer`
Get detailed information about a specific server.
**Example**:
```
Show me details for server srv_123abc
```
**Parameters**:
- `id` (required): Server ID
**Response**:
```json
{
"id": "srv_123abc",
"name": "production-api",
"host": "192.168.1.100",
"port": 8080,
"status": "running",
"tags": ["production", "api"],
"config": {
"memory": "2GB",
"cpu": "2 cores"
},
"metrics": {
"uptime": "15d 4h 30m",
"cpu_usage": "45%",
"memory_usage": "1.2GB"
},
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-26T14:20:00Z"
}
```
### Deployments
#### List Deployments
**Tool**: `komodo_read_ListDeployments`
List all deployments with filtering options.
**Example**:
```
Show all deployments on server srv_123abc
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `server_id` (optional): Filter by server
- `status` (optional): Filter by status (running, stopped, deploying, failed)
**Response**:
```json
{
"items": [
{
"id": "dep_456def",
"name": "api-v2",
"server_id": "srv_123abc",
"status": "running",
"image": "myapp:v2.1.0",
"ports": ["8080:80"],
"env": {
"NODE_ENV": "production"
},
"createdAt": "2026-01-20T08:00:00Z",
"updatedAt": "2026-01-26T12:00:00Z"
}
],
"total": 1,
"page": 1,
"pageSize": 50
}
```
#### Get Deployment
**Tool**: `komodo_read_GetDeployment`
Get detailed deployment information.
**Example**:
```
Get details for deployment dep_456def
```
**Parameters**:
- `id` (required): Deployment ID
### Stacks
#### List Stacks
**Tool**: `komodo_read_ListStacks`
List all Docker Compose stacks.
**Example**:
```
Show all active stacks
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `status` (optional): Filter by status (active, inactive, deploying)
#### Get Stack
**Tool**: `komodo_read_GetStack`
Get stack details including all services.
**Example**:
```
Get stack stk_789ghi details
```
**Parameters**:
- `id` (required): Stack ID
### Builds
#### List Builds
**Tool**: `komodo_read_ListBuilds`
List all build configurations.
**Example**:
```
Show all builds for repository repo_abc123
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `repo_id` (optional): Filter by repository
- `status` (optional): Filter by status (pending, building, success, failed)
#### Get Build
**Tool**: `komodo_read_GetBuild`
Get build configuration and history.
**Example**:
```
Show build bld_xyz789 details
```
**Parameters**:
- `id` (required): Build ID
### Repositories
#### List Repos
**Tool**: `komodo_read_ListRepos`
List all connected repositories.
**Example**:
```
Show all GitHub repositories
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `provider` (optional): Filter by provider (github, gitlab, bitbucket, other)
#### Get Repo
**Tool**: `komodo_read_GetRepo`
Get repository details and status.
**Example**:
```
Get repository repo_abc123 info
```
**Parameters**:
- `id` (required): Repository ID
### Procedures
#### List Procedures
**Tool**: `komodo_read_ListProcedures`
List all automation procedures.
**Example**:
```
Show all manual trigger procedures
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `trigger` (optional): Filter by trigger type (manual, scheduled, webhook)
#### Get Procedure
**Tool**: `komodo_read_GetProcedure`
Get procedure configuration and execution history.
**Example**:
```
Show procedure proc_123 details
```
**Parameters**:
- `id` (required): Procedure ID
### Actions
#### List Actions
**Tool**: `komodo_read_ListActions`
List all configured actions.
**Example**:
```
Show all enabled script actions
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `type` (optional): Filter by type (script, api, notification)
- `enabled` (optional): Filter by enabled status
#### Get Action
**Tool**: `komodo_read_GetAction`
Get action details and execution logs.
**Example**:
```
Get action act_456 info
```
**Parameters**:
- `id` (required): Action ID
### Alerts
#### List Alerts
**Tool**: `komodo_read_ListAlerts`
List all system alerts.
**Example**:
```
Show all critical unresolved alerts
```
**Parameters**:
- `page` (optional): Page number
- `page_size` (optional): Items per page
- `severity` (optional): Filter by severity (info, warning, error, critical)
- `resolved` (optional): Filter by resolved status
- `resource_type` (optional): Filter by resource type
#### Get Alert
**Tool**: `komodo_read_GetAlert`
Get detailed alert information.
**Example**:
```
Get alert alt_789 details
```
**Parameters**:
- `id` (required): Alert ID
---
## Execute Module
The execute module triggers actions on Komodo resources. These operations have side effects and may be long-running.
### Deployments
#### Execute Deploy
**Tool**: `komodo_execute_Deploy`
Execute a deployment.
**Example**:
```
Deploy deployment dep_456def
```
**Parameters**:
- `id` (required): Deployment ID
- `options` (optional):
- `force` (boolean): Force deploy even if no changes
- `stopBeforeStart` (boolean): Stop before starting
- `skipPull` (boolean): Skip pulling latest code
**Response**:
```json
{
"job_id": "job_deploy_123",
"status": "started",
"deployment_id": "dep_456def",
"started_at": "2026-01-26T15:30:00Z",
"estimated_duration": "2-5 minutes"
}
```
### Builds
#### Trigger Build
**Tool**: `komodo_execute_Build`
Trigger a build process.
**Example**:
```
Build bld_xyz789 with no cache
```
**Parameters**:
- `id` (required): Build ID
- `options` (optional):
- `skipCache` (boolean): Skip cached layers
- `skipPull` (boolean): Skip pulling code
- `forceBuild` (boolean): Force rebuild
**Response**:
```json
{
"job_id": "job_build_456",
"status": "building",
"build_id": "bld_xyz789",
"started_at": "2026-01-26T15:35:00Z",
"log_url": "https://komodo.example.com/builds/bld_xyz789/logs/job_build_456"
}
```
### Server Lifecycle
#### Start Server
**Tool**: `komodo_execute_StartServer`
Start a server.
**Example**:
```
Start server srv_123abc
```
**Parameters**:
- `id` (required): Server ID
- `options` (optional):
- `timeout` (number): Startup timeout in seconds
- `waitForHealthy` (boolean): Wait for healthy status
**Response**:
```json
{
"server_id": "srv_123abc",
"status": "starting",
"started_at": "2026-01-26T15:40:00Z"
}
```
#### Stop Server
**Tool**: `komodo_execute_StopServer`
Stop a running server.
**Example**:
```
Stop server srv_123abc gracefully
```
**Parameters**:
- `id` (required): Server ID
- `options` (optional):
- `timeout` (number): Shutdown timeout
- `force` (boolean): Force stop (SIGKILL)
- `removeContainer` (boolean): Remove container after stop
#### Restart Server
**Tool**: `komodo_execute_RestartServer`
Restart a server.
**Example**:
```
Restart server srv_123abc and wait for it to be healthy
```
**Parameters**:
- `id` (required): Server ID
- `options` (optional):
- `timeout` (number): Restart timeout
- `force` (boolean): Force restart
- `waitForHealthy` (boolean): Wait for healthy status
### Procedures
#### Run Procedure
**Tool**: `komodo_execute_RunProcedure`
Execute a procedure.
**Example**:
```
Run procedure proc_123 with variable ENV=production
```
**Parameters**:
- `id` (required): Procedure ID
- `variables` (optional): Key-value pairs to pass to procedure
- `options` (optional):
- `async` (boolean): Run asynchronously
- `timeout` (number): Execution timeout
**Response**:
```json
{
"execution_id": "exec_789",
"procedure_id": "proc_123",
"status": "running",
"started_at": "2026-01-26T15:45:00Z",
"variables": {
"ENV": "production"
}
}
```
### Actions
#### Trigger Action
**Tool**: `komodo_execute_TriggerAction`
Trigger an action.
**Example**:
```
Trigger action act_456 with payload {"target": "production"}
```
**Parameters**:
- `id` (required): Action ID
- `payload` (optional): Data to pass to action
- `options` (optional):
- `async` (boolean): Execute asynchronously
- `retryOnFailure` (boolean): Retry if fails
### Repository Operations
#### Pull Repo
**Tool**: `komodo_execute_PullRepo`
Pull latest changes from repository.
**Example**:
```
Pull latest changes for repo_abc123 on main branch
```
**Parameters**:
- `id` (required): Repository ID
- `options` (optional):
- `branch` (string): Specific branch to pull
- `force` (boolean): Force pull, discard local changes
- `submodules` (boolean): Update submodules
#### Clone Repo
**Tool**: `komodo_execute_CloneRepo`
Clone a repository.
**Example**:
```
Clone repository repo_abc123
```
**Parameters**:
- `id` (required): Repository ID
- `options` (optional):
- `branch` (string): Specific branch
- `depth` (number): Shallow clone depth
- `submodules` (boolean): Clone submodules
- `overwrite` (boolean): Overwrite if exists
---
## Common Patterns
### Server Management Workflow
```
1. List all servers
"Show me all my servers"
2. Check specific server status
"Get details for server srv_123abc"
3. Restart if needed
"Restart server srv_123abc"
4. Verify it's running
"Check status of server srv_123abc"
```
### Deployment Workflow
```
1. Check current deployments
"Show all deployments on production servers"
2. Trigger new deployment
"Deploy dep_456def with force option"
3. Monitor deployment status
"Get deployment dep_456def status"
4. Verify running
"Show all running deployments"
```
### Build and Deploy Pipeline
```
1. List builds for a repo
"Show builds for repository repo_abc123"
2. Trigger new build
"Build bld_xyz789 with no cache"
3. Monitor build progress
"Get build bld_xyz789 status"
4. Deploy when ready
"Deploy dep_456def"
```
### Alert Management
```
1. Check for critical alerts
"Show all critical unresolved alerts"
2. Get alert details
"Get alert alt_789 details"
3. Investigate related resource
"Get server srv_123abc info" (based on alert)
4. Take corrective action
"Restart server srv_123abc"
```
---
## Error Handling
### Common Errors
#### Authentication Errors
**401 Unauthorized**
```json
{
"error": "Invalid API credentials",
"code": "AUTH_ERROR"
}
```
**Solution**: Verify `KOMODO_API_KEY` and `KOMODO_API_SECRET` are correct.
#### Not Found Errors
**404 Not Found**
```json
{
"error": "Server not found: srv_invalid",
"code": "NOT_FOUND"
}
```
**Solution**: Verify the resource ID is correct. Use list commands to find valid IDs.
#### Validation Errors
**400 Bad Request**
```json
{
"error": "Missing required field: id",
"code": "VALIDATION_ERROR"
}
```
**Solution**: Check the tool documentation for required parameters.
#### Network Errors
**Connection Failed**
```json
{
"error": "Network request failed",
"code": "NETWORK_ERROR"
}
```
**Solution**:
- Verify `KOMODO_URL` is correct
- Check network connectivity
- Ensure Komodo server is running
### Retry Behavior
The MCP server automatically retries failed requests:
- **Retryable**: 5xx server errors, network failures
- **Not Retryable**: 4xx client errors (validation, auth, not found)
- **Max Retries**: 3 (configurable with `KOMODO_RETRY_COUNT`)
- **Retry Delay**: 1 second with exponential backoff (configurable with `KOMODO_RETRY_DELAY`)
---
## Best Practices
### 1. Use Filters for Large Lists
Instead of:
```
Show all deployments
```
Use:
```
Show running deployments on server srv_123abc
```
### 2. Check Status Before Actions
Before executing operations:
```
Get server srv_123abc status
```
Then:
```
Restart server srv_123abc if status is error
```
### 3. Use Pagination for Large Results
```
Show first 20 servers
Show next 20 servers (page 2)
```
### 4. Verify Success After Execute Operations
```
Deploy dep_456def
... wait ...
Get deployment dep_456def status
```
### 5. Handle Async Operations
For long-running operations, use async mode:
```
Run procedure proc_123 asynchronously
```
Then check status periodically:
```
Get procedure proc_123 last execution status
```
### 6. Use Descriptive Queries
Instead of:
```
Get srv_123abc
```
Use:
```
Show production API server details
Get server named production-api
```
Claude will map your natural language to the correct tool and parameters.
### 7. Batch Related Operations
Group related queries:
```
Show me:
1. All servers
2. Deployments on each server
3. Any critical alerts
```
Claude will execute multiple tools efficiently.
### 8. Leverage Natural Language
You don't need to memorize tool names:
- "List my servers" → `komodo_read_ListServers`
- "Deploy my app" → `komodo_execute_Deploy`
- "Restart the API server" → `komodo_execute_RestartServer`
Just describe what you want in natural language.
---
## Next Steps
- Review the [API Reference](./API_REFERENCE.md) for complete parameter documentation
- Check [Troubleshooting](./TROUBLESHOOTING.md) for common issues
- See [Examples](./EXAMPLES.md) for real-world scenarios
- Read [Migration Guide](./MIGRATION.md) if transitioning from direct API usage
