mcp-cldkctl 0.1.2

MCP server for Cloudeka CLI (cldkctl) integration with authentication support

MCP cldkctl Server

This is a Model Context Protocol (MCP) server that provides integration with the Cloudeka CLI (cldkctl) for use in AI assistants like Claude Desktop and Cursor.

Features

The MCP server exposes the following cldkctl commands as tools:

• Authentication: Login and token management
• Balance: View project balances
• Billing: View billing details
• Kubernetes: Manage Kubernetes resources (pods, deployments, services, etc.)
• Organization: Manage organization details and members
• Profile: View and manage user profile
• Project: View and manage projects
• Registry: Manage container registry
• VMs: Manage virtual machines
• Voucher: Manage vouchers and credits
• Notebook: Manage notebooks
• Audit Logs: View activity logs

Prerequisites

• Python 3.10 or higher
• uv package manager
• cldkctl CLI tool installed and in PATH

Installation

Quick Install

# Clone the repository
git clone <repository-url>
cd mcp_cldkctl

# Run the installation script
# On Windows:
.\install.ps1

# On Unix/Linux/macOS:
./install.sh

Manual Installation

# Clone the repository
git clone <repository-url>
cd mcp_cldkctl

# Install dependencies using uv
uv sync

# Install the package
uv pip install -e .

Usage

Running the MCP Server

# Run with stdio transport (default)
uvx mcp-cldkctl

# Run with SSE transport
uvx mcp-cldkctl --transport sse --port 8000

# Specify custom cldkctl path
uvx mcp-cldkctl --cldkctl-path /path/to/cldkctl

Configuration

The server will use the same configuration as your cldkctl CLI. Make sure you have:

1. Authenticated with cldkctl auth
2. Set up your default project, organization, and other preferences
3. The cldkctl binary available in your PATH

Integration with Cursor

Add this to your Cursor MCP configuration:

{
  "mcpServers": {
    "cldkctl": {
      "command": "uvx",
      "args": ["mcp-cldkctl"]
    }
  }
}

Integration with Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "cldkctl": {
      "command": "uvx",
      "args": ["mcp-cldkctl"]
    }
  }
}

Testing

Run the test script to verify your installation:

python test_server.py

This will:

• Check if cldkctl is available
• Test basic command execution
• Show you the Cursor configuration

Available Tools

Authentication

• auth: Authenticate with Cloudeka service using token

Balance & Billing

• balance: View balance for each project
• billing: View project billing details

Kubernetes Management

• kubernetes: Manage Kubernetes resources (pods, deployments, services, etc.)

Organization & Project Management

• organization: Manage organization details, members, and roles
• project: View and manage your projects

Infrastructure Management

• vm: Manage virtual machines (VMs)
• registry: Manage your container registry
• notebook: Manage notebooks

User Management

• profile: View and manage your profile information
• token: View and manage your Cloudeka authentication tokens

Financial Management

• voucher: Manage project vouchers and credit balances

Monitoring

• logs: View and manage activity logs in the organization's cloud

Examples

See examples/usage_examples.md for detailed usage examples.

Development

# Install development dependencies
uv sync --group dev

# Run tests
uv run pytest

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

Troubleshooting

cldkctl not found

Make sure cldkctl is installed and available in your PATH. You can specify a custom path using the --cldkctl-path option.

AttributeError: module 'mcp.types' has no attribute 'ContentBlock'

This means your MCP SDK is outdated or not installed in editable mode. Either:

• Update your MCP SDK (from your local python-sdk if possible):

  pip install -e ../python-sdk
  # or
  uv pip install -e ../python-sdk
  

• Or, use the latest version from PyPI:

  pip install --upgrade mcp
  

• Or, use the correct union type in your code (already fixed in this repo):

  types.TextContent | types.ImageContent | types.AudioContent | types.ResourceLink | types.EmbeddedResource
  

Authentication errors

Ensure you're authenticated with cldkctl first:

cldkctl auth your-token

Permission errors

Make sure you have the necessary permissions to execute cldkctl commands and access the required resources.

Connection issues

Check your network connection and ensure you can reach the Cloudeka API endpoints.

PyPI Build/Publish Checklist

• Make sure your pyproject.toml has all required fields (name, version, description, authors, license, etc.)
• Make sure your package builds locally:

  python -m build
  

• Make sure you have a valid PyPI token and credentials
• Publish with:

  twine upload dist/*
  

• If using build_and_publish.py, check its output for errors
• If you see missing file errors, ensure README.md, LICENSE, and all Python files are included in the build

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License

Support

For issues and questions:

• Check the troubleshooting section
• Review the usage examples
• Open an issue on the repository