MCP cldkctl Server
A Model Context Protocol (MCP) server that provides full access to Cloudeka's cldkctl CLI functionality through Claude Desktop, Cursor, and other MCP-compatible clients.
Features
- Smart Authentication: Automatic environment fallback (production -> staging)
- Auto-Reauthentication: Handles token expiry automatically
- Complete API Coverage: All cldkctl endpoints available as MCP tools
- Persistent Caching: JWT tokens cached locally for performance
- Environment Management: Easy switching between production and staging
- Full Tool Suite: Kubernetes, billing, VMs, registry, notebooks, and more
Installation
From PyPI
pip install mcp-cldkctl
# or
uvx mcp-cldkctl
From Source
git clone https://github.com/cloudeka/mcp-cldkctl.git
cd mcp-cldkctl
pip install -e .
# or
uv sync
Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
CLDKCTL_TOKEN | Yes | - | Your cldkctl token (starts with cldkctl_) |
CLDKCTL_BASE_URL | No | https://ai.cloudeka.id | Base URL (auto-fallback to staging if production fails) |
CLDKCTL_DEFAULT_PROJECT_ID | No | - | Default project ID for convenience |
Example Setup
Linux/macOS:
export CLDKCTL_TOKEN="cldkctl_your_token_here"
export CLDKCTL_BASE_URL="https://ai.cloudeka.id"
export CLDKCTL_DEFAULT_PROJECT_ID="your_project_id"
Windows:
set CLDKCTL_TOKEN=cldkctl_your_token_here
set CLDKCTL_BASE_URL=https://ai.cloudeka.id
set CLDKCTL_DEFAULT_PROJECT_ID=your_project_id
Usage
Running the Server
# Using uvx (recommended)
uvx mcp-cldkctl
# Direct execution
python -m mcp_cldkctl.server
# Using the installed script
mcp-cldkctl
Claude Desktop Configuration
Add this to your Claude Desktop configuration:
{
"mcpServers": {
"cldkctl": {
"command": "uvx",
"args": ["mcp-cldkctl"],
"env": {
"CLDKCTL_TOKEN": "your_cldkctl_token_here",
"CLDKCTL_BASE_URL": "https://ai.cloudeka.id"
}
}
}
}
Cursor Configuration
Add this to your Cursor settings:
{
"mcpServers": {
"cldkctl": {
"command": "uvx",
"args": ["mcp-cldkctl"],
"env": {
"CLDKCTL_TOKEN": "your_cldkctl_token_here"
}
}
}
}
Development
For development, install the package with development dependencies:
pip install -e ".[dev]"
Available Tools
Authentication & Environment
auth- Authenticate with your cldkctl tokenswitch_environment- Switch between production/stagingstatus- Check current environment and auth status
Balance & Billing
balance_detail- Get project balance detailsbilling_daily_cost- Get daily billing costsbilling_monthly_cost- Get monthly billing costsbilling_history- Get billing history
Kubernetes Management
k8s_pods- List Kubernetes podsk8s_deployments- List Kubernetes deploymentsk8s_services- List Kubernetes servicesk8s_configmaps- List Kubernetes configmapsk8s_secrets- List Kubernetes secrets
Project & Organization
project_list- List all projectsproject_detail- Get project detailsorg_detail- Get organization detailsorg_members- List organization membersprofile_detail- Get user profile
Virtual Machines
vm_list- List virtual machinesvm_detail- Get VM details
Container Registry
registry_list- List container registriesregistry_repositories- List registry repositories
Notebooks
notebook_list- List Deka notebooksnotebook_create- Create a new notebook
Vouchers & Tokens
voucher_list- List available vouchersvoucher_apply- Apply a voucher codetoken_list- List cldkctl tokenstoken_create- Create a new tokentoken_delete- Delete a token
Logs
audit_logs- Get audit logs
Environment Fallback
The MCP server automatically handles environment issues:
- Tries production first (
https://ai.cloudeka.id) - Detects database errors (missing
cldkctl_tokenstable) - Auto-fallbacks to staging (
https://staging.ai.cloudeka.id) - Caches the working environment for future requests
Manual Environment Switching
# Switch to staging
switch_environment(environment="staging")
# Switch to production
switch_environment(environment="production")
# Check current status
status()
Authentication Flow
- Initial Auth: Exchange cldkctl token for JWT
- Token Caching: JWT stored locally with 24-hour expiry
- Auto-Reauth: Automatically re-authenticate when token expires
- Environment Persistence: Remember which environment works
Example Usage
Basic Authentication
# Authenticate (auto-fallback if production fails)
auth(token="cldkctl_your_token_here")
# Check status
status()
Project Management
# List all projects
project_list()
# Get specific project details
project_detail(project_id="your_project_id")
Kubernetes Operations
# List pods in default namespace
k8s_pods(project_id="your_project_id")
# List deployments in specific namespace
k8s_deployments(project_id="your_project_id", namespace="kube-system")
Billing Queries
# Get daily costs
billing_daily_cost(project_id="your_project_id")
# Get billing history
billing_history(
project_id="your_project_id",
start_date="2024-01-01",
end_date="2024-01-31"
)
Troubleshooting
Common Issues
Authentication Failed
- Check your
CLDKCTL_TOKENis valid - Ensure token starts with
cldkctl_ - Try using staging environment manually
Production Database Error
- This is normal - the server auto-fallbacks to staging
- Check status to see which environment is active
Token Expired
- The server auto-reauthenticates
- Check status to verify authentication
Environment Issues
# Force staging environment
auth(token="your_token", force_staging=True)
# Check current environment
status()
Version History
Current version: 1.0.0 (Production)
License
MIT License
Security
Never commit your real tokens, secrets, or credentials to the repository. All authentication is handled via environment variables or user input. Example tokens in this documentation are placeholders only.