Komodo MCP Server

An MCP (Model Context Protocol) server for interacting with the Komodo Client API, built with FastMCP.

Overview

This MCP server provides a comprehensive interface to the Komodo API, allowing you to manage deployments, builds, stacks, servers, and execute commands through MCP-compatible clients. It exposes all major Komodo API operations as MCP tools.

Related MCP server: Promethean OS MCP

Features

• Complete API Coverage: Supports all Komodo API modules (auth, user, read, write, execute, terminal)

• Type-Safe: Built with Pydantic for request/response validation

• Error Handling: Comprehensive error handling with clear error messages

• Flexible Configuration: Supports client-provided configuration or environment variables

• Docker Support: Ready-to-use Docker containerization

• FastMCP Integration: Built on FastMCP for reliable MCP protocol handling

Installation

Prerequisites

• Python 3.12 or later

• Access to a Komodo instance

• Komodo API credentials (API key and secret)

Install Dependencies

pip install -e .

Or install dependencies directly:

pip install fastmcp httpx pydantic python-dotenv

Configuration

The server supports two configuration methods:

Method 1: Client-Provided Configuration (Recommended)

Provide configuration during MCP server initialization. This is the preferred method as it keeps credentials out of environment variables.

MCP Client Configuration Example:

{
  "mcpServers": {
    "komodo": {
      "command": "python",
      "args": ["-m", "komodo_mcp.main"],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}

Alternative parameter names (also supported):

• address instead of komodo_address

• api_key instead of komodo_api_key

• api_secret instead of komodo_api_secret

Method 2: Environment Variables (Fallback)

If client-provided configuration is not available, the server will fall back to environment variables.

Create a .env file in the project root (or copy from .env.example):

cp .env.example .env

Edit .env with your Komodo credentials:

KOMODO_ADDRESS=https://komodo.example.com
KOMODO_API_KEY=your_api_key_here
KOMODO_API_SECRET=your_api_secret_here

Environment Variables:

• KOMODO_ADDRESS (required): Base URL of your Komodo instance (e.g., https://komodo.example.com)

• KOMODO_API_KEY (required): Your Komodo API key

• KOMODO_API_SECRET (required): Your Komodo API secret

You can obtain API credentials from the Komodo UI Settings page.

Configuration Priority:

1. Client-provided initialization options (highest priority)

2. Environment variables (fallback)

Usage

Running the Server Locally

The server runs using stdio transport (standard for MCP):

python -m komodo_mcp.main

Or use the installed script:

komodo-mcp

Running with Docker

Build the Docker Image

docker build -f docker/Dockerfile -t komodo-mcp .

Run the Container

With environment variables:

docker run -it --rm \
  -e KOMODO_ADDRESS=https://komodo.example.com \
  -e KOMODO_API_KEY=your_api_key \
  -e KOMODO_API_SECRET=your_api_secret \
  komodo-mcp

With docker-compose:

# Set environment variables in .env file or export them
export KOMODO_ADDRESS=https://komodo.example.com
export KOMODO_API_KEY=your_api_key
export KOMODO_API_SECRET=your_api_secret

docker-compose up

With client-provided configuration:

The Docker container can be used with client-provided configuration. Configure your MCP client to connect to the Docker container:

{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "komodo-mcp"
      ],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}

MCP Client Configuration

Local Installation:

{
  "mcpServers": {
    "komodo": {
      "command": "python",
      "args": ["-m", "komodo_mcp.main"],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}

Docker Installation:

{
  "mcpServers": {
    "komodo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "komodo-mcp"
      ],
      "initializationOptions": {
        "komodo_address": "https://komodo.example.com",
        "komodo_api_key": "your_api_key",
        "komodo_api_secret": "your_api_secret"
      }
    }
  }
}

Available Tools

Authentication

• komodo_login: Login to Komodo and obtain authentication token

User Management

• komodo_list_api_keys: List all API keys for the current user

• komodo_create_api_key: Create a new API key

• komodo_delete_api_key: Delete an API key

Read Operations

• komodo_get_deployment: Get detailed information about a deployment

• komodo_list_deployments: List all deployments

• komodo_get_build: Get detailed information about a build

• komodo_list_builds: List all builds

• komodo_get_stack: Get detailed information about a stack

• komodo_list_stacks: List all stacks

• komodo_get_server: Get detailed information about a server

• komodo_list_servers: List all servers

Write Operations

• komodo_create_deployment: Create a new deployment

• komodo_update_deployment: Update an existing deployment

• komodo_delete_deployment: Delete a deployment

• komodo_create_build: Create a new build

• komodo_update_build: Update an existing build

• komodo_delete_build: Delete a build

• komodo_create_stack: Create a new stack

• komodo_update_stack: Update an existing stack

• komodo_delete_stack: Delete a stack

• komodo_create_server: Create a new server

• komodo_update_server: Update an existing server

• komodo_delete_server: Delete a server

Execute Operations

• komodo_run_build: Execute/run a build

• komodo_run_deployment: Execute/run a deployment

• komodo_stop_build: Stop a running build

• komodo_stop_deployment: Stop a running deployment

Terminal Operations

• komodo_execute_command: Execute a command on a server via terminal

Examples

List All Deployments

# Using an MCP client
result = await client.call_tool("komodo_list_deployments")
print(result)

Create a Deployment

config = {
    "name": "my-deployment",
    "build": "build-id-here",
    # ... other deployment config
}
result = await client.call_tool("komodo_create_deployment", {"config": config})
print(result)

Run a Build

result = await client.call_tool("komodo_run_build", {
    "build": "build-id-here",
    "options": {
        "environment": "production"
    }
})
print(result)

Execute a Command on a Server

result = await client.call_tool("komodo_execute_command", {
    "server": "server-id-here",
    "command": "docker ps",
    "options": {
        "timeout": 30
    }
})
print(result)

Error Handling

The server provides comprehensive error handling:

• KomodoConfigError: Raised when configuration is invalid or missing

• KomodoAPIError: Raised when Komodo API returns an error (includes error message and traceback)

• KomodoConnectionError: Raised when connection to Komodo API fails

All errors are properly formatted and include helpful error messages.

Development

Project Structure

komodo-mcp/
├── src/
│   └── komodo_mcp/
│       ├── __init__.py
│       ├── main.py              # Entry point
│       ├── server.py            # FastMCP server with all tools
│       ├── client.py            # Komodo HTTP client
│       ├── config.py            # Configuration management
│       ├── errors.py            # Custom exceptions
│       ├── models.py            # Pydantic models
│       └── tools/               # Tool modules
│           ├── __init__.py
│           ├── auth.py
│           ├── user.py
│           ├── read.py
│           ├── write.py
│           ├── execute.py
│           └── terminal.py
├── tests/                       # Test files
│   └── __init__.py
├── docker/
│   └── Dockerfile               # Docker image definition
├── docker-compose.yml           # Docker Compose configuration
├── .dockerignore                # Docker ignore patterns
├── pyproject.toml               # Project configuration
├── .env.example                  # Environment variable template
├── .gitignore
└── README.md

Running Tests

pytest

Docker Development

For development with Docker, you can mount the source code:

# In docker-compose.yml, uncomment the volumes section:
volumes:
  - ./src:/app/src:ro

Then rebuild and run:

docker-compose up --build

Docker Details

Image Size Optimization

The Docker image uses Python 3.12-slim for a smaller footprint. The image includes:

• Python 3.12 runtime

• Project dependencies

• Non-root user for security

• Optimized layer caching

Security Considerations

• Runs as non-root user (komodo)

• No unnecessary packages installed

• Environment variables can be provided at runtime

• Supports client-provided configuration (no secrets in image)

MCP Protocol Support

MCP servers use stdio transport, so:

• No ports need to be exposed

• Communication happens via stdin/stdout

• Works seamlessly with Docker's stdio support

License

This project is licensed under the same license as the Komodo Client API.

References

• Komodo Client API Documentation

• FastMCP Documentation