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.

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