| Name | mcp-cldkctl JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | MCP server for Cloudeka cldkctl CLI integration with automatic environment fallback (Testing Version) |
| upload_time | 2025-07-14 02:56:59 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
cldkctl
cli
cloud
cloudeka
kubernetes
mcp
testing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
```bash
pip install mcp-cldkctl
# or
uvx mcp-cldkctl
```
### From Source
```bash
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:**
```bash
export CLDKCTL_TOKEN="cldkctl_your_token_here"
export CLDKCTL_BASE_URL="https://ai.cloudeka.id"
export CLDKCTL_DEFAULT_PROJECT_ID="your_project_id"
```
**Windows:**
```cmd
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
```bash
# 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:
```json
{
"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:
```json
{
"mcpServers": {
"cldkctl": {
"command": "uvx",
"args": ["mcp-cldkctl"],
"env": {
"CLDKCTL_TOKEN": "your_cldkctl_token_here"
}
}
}
}
```
## Development
For development, install the package with development dependencies:
```bash
pip install -e ".[dev]"
```
## Available Tools
### Authentication & Environment
- **`auth`** - Authenticate with your cldkctl token
- **`switch_environment`** - Switch between production/staging
- **`status`** - Check current environment and auth status
### Balance & Billing
- **`balance_detail`** - Get project balance details
- **`billing_daily_cost`** - Get daily billing costs
- **`billing_monthly_cost`** - Get monthly billing costs
- **`billing_history`** - Get billing history
### Kubernetes Management
- **`k8s_pods`** - List Kubernetes pods
- **`k8s_deployments`** - List Kubernetes deployments
- **`k8s_services`** - List Kubernetes services
- **`k8s_configmaps`** - List Kubernetes configmaps
- **`k8s_secrets`** - List Kubernetes secrets
### Project & Organization
- **`project_list`** - List all projects
- **`project_detail`** - Get project details
- **`org_detail`** - Get organization details
- **`org_members`** - List organization members
- **`profile_detail`** - Get user profile
### Virtual Machines
- **`vm_list`** - List virtual machines
- **`vm_detail`** - Get VM details
### Container Registry
- **`registry_list`** - List container registries
- **`registry_repositories`** - List registry repositories
### Notebooks
- **`notebook_list`** - List Deka notebooks
- **`notebook_create`** - Create a new notebook
### Vouchers & Tokens
- **`voucher_list`** - List available vouchers
- **`voucher_apply`** - Apply a voucher code
- **`token_list`** - List cldkctl tokens
- **`token_create`** - Create a new token
- **`token_delete`** - Delete a token
### Logs
- **`audit_logs`** - Get audit logs
## Environment Fallback
The MCP server automatically handles environment issues:
1. **Tries production first** (`https://ai.cloudeka.id`)
2. **Detects database errors** (missing `cldkctl_tokens` table)
3. **Auto-fallbacks to staging** (`https://staging.ai.cloudeka.id`)
4. **Caches the working environment** for future requests
### Manual Environment Switching
```python
# Switch to staging
switch_environment(environment="staging")
# Switch to production
switch_environment(environment="production")
# Check current status
status()
```
## Authentication Flow
1. **Initial Auth**: Exchange cldkctl token for JWT
2. **Token Caching**: JWT stored locally with 24-hour expiry
3. **Auto-Reauth**: Automatically re-authenticate when token expires
4. **Environment Persistence**: Remember which environment works
## Example Usage
### Basic Authentication
```python
# Authenticate (auto-fallback if production fails)
auth(token="cldkctl_your_token_here")
# Check status
status()
```
### Project Management
```python
# List all projects
project_list()
# Get specific project details
project_detail(project_id="your_project_id")
```
### Kubernetes Operations
```python
# 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
```python
# 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_TOKEN` is 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**
```python
# 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.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-cldkctl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cldkctl, cli, cloud, cloudeka, kubernetes, mcp, testing",
"author": null,
"author_email": "Cloudeka MCP Team <support@cloudeka.id>",
"download_url": "https://files.pythonhosted.org/packages/45/07/2ee3c33282025387c8a372539f84a4fe95d1eae8492ae96ead1873fe87b2/mcp_cldkctl-0.3.0.tar.gz",
"platform": null,
"description": "# MCP cldkctl Server\n\nA Model Context Protocol (MCP) server that provides full access to Cloudeka's cldkctl CLI functionality through Claude Desktop, Cursor, and other MCP-compatible clients.\n\n## Features\n\n- **Smart Authentication**: Automatic environment fallback (production -> staging)\n- **Auto-Reauthentication**: Handles token expiry automatically\n- **Complete API Coverage**: All cldkctl endpoints available as MCP tools\n- **Persistent Caching**: JWT tokens cached locally for performance\n- **Environment Management**: Easy switching between production and staging\n- **Full Tool Suite**: Kubernetes, billing, VMs, registry, notebooks, and more\n\n## Installation\n\n### From PyPI\n\n```bash\npip install mcp-cldkctl\n# or\nuvx mcp-cldkctl\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/cloudeka/mcp-cldkctl.git\ncd mcp-cldkctl\npip install -e .\n# or\nuv sync\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `CLDKCTL_TOKEN` | Yes | - | Your cldkctl token (starts with `cldkctl_`) |\n| `CLDKCTL_BASE_URL` | No | `https://ai.cloudeka.id` | Base URL (auto-fallback to staging if production fails) |\n| `CLDKCTL_DEFAULT_PROJECT_ID` | No | - | Default project ID for convenience |\n\n### Example Setup\n\n**Linux/macOS:**\n```bash\nexport CLDKCTL_TOKEN=\"cldkctl_your_token_here\"\nexport CLDKCTL_BASE_URL=\"https://ai.cloudeka.id\"\nexport CLDKCTL_DEFAULT_PROJECT_ID=\"your_project_id\"\n```\n\n**Windows:**\n```cmd\nset CLDKCTL_TOKEN=cldkctl_your_token_here\nset CLDKCTL_BASE_URL=https://ai.cloudeka.id\nset CLDKCTL_DEFAULT_PROJECT_ID=your_project_id\n```\n\n## Usage\n\n### Running the Server\n\n```bash\n# Using uvx (recommended)\nuvx mcp-cldkctl\n\n# Direct execution\npython -m mcp_cldkctl.server\n\n# Using the installed script\nmcp-cldkctl\n```\n\n### Claude Desktop Configuration\n\nAdd this to your Claude Desktop configuration:\n\n```json\n{\n \"mcpServers\": {\n \"cldkctl\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-cldkctl\"],\n \"env\": {\n \"CLDKCTL_TOKEN\": \"your_cldkctl_token_here\",\n \"CLDKCTL_BASE_URL\": \"https://ai.cloudeka.id\"\n }\n }\n }\n}\n```\n\n### Cursor Configuration\n\nAdd this to your Cursor settings:\n\n```json\n{\n \"mcpServers\": {\n \"cldkctl\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-cldkctl\"],\n \"env\": {\n \"CLDKCTL_TOKEN\": \"your_cldkctl_token_here\"\n }\n }\n }\n}\n```\n\n## Development\n\nFor development, install the package with development dependencies:\n\n```bash\npip install -e \".[dev]\"\n```\n\n## Available Tools\n\n### Authentication & Environment\n- **`auth`** - Authenticate with your cldkctl token\n- **`switch_environment`** - Switch between production/staging\n- **`status`** - Check current environment and auth status\n\n### Balance & Billing\n- **`balance_detail`** - Get project balance details\n- **`billing_daily_cost`** - Get daily billing costs\n- **`billing_monthly_cost`** - Get monthly billing costs\n- **`billing_history`** - Get billing history\n\n### Kubernetes Management\n- **`k8s_pods`** - List Kubernetes pods\n- **`k8s_deployments`** - List Kubernetes deployments\n- **`k8s_services`** - List Kubernetes services\n- **`k8s_configmaps`** - List Kubernetes configmaps\n- **`k8s_secrets`** - List Kubernetes secrets\n\n### Project & Organization\n- **`project_list`** - List all projects\n- **`project_detail`** - Get project details\n- **`org_detail`** - Get organization details\n- **`org_members`** - List organization members\n- **`profile_detail`** - Get user profile\n\n### Virtual Machines\n- **`vm_list`** - List virtual machines\n- **`vm_detail`** - Get VM details\n\n### Container Registry\n- **`registry_list`** - List container registries\n- **`registry_repositories`** - List registry repositories\n\n### Notebooks\n- **`notebook_list`** - List Deka notebooks\n- **`notebook_create`** - Create a new notebook\n\n### Vouchers & Tokens\n- **`voucher_list`** - List available vouchers\n- **`voucher_apply`** - Apply a voucher code\n- **`token_list`** - List cldkctl tokens\n- **`token_create`** - Create a new token\n- **`token_delete`** - Delete a token\n\n### Logs\n- **`audit_logs`** - Get audit logs\n\n## Environment Fallback\n\nThe MCP server automatically handles environment issues:\n\n1. **Tries production first** (`https://ai.cloudeka.id`)\n2. **Detects database errors** (missing `cldkctl_tokens` table)\n3. **Auto-fallbacks to staging** (`https://staging.ai.cloudeka.id`)\n4. **Caches the working environment** for future requests\n\n### Manual Environment Switching\n\n```python\n# Switch to staging\nswitch_environment(environment=\"staging\")\n\n# Switch to production\nswitch_environment(environment=\"production\")\n\n# Check current status\nstatus()\n```\n\n## Authentication Flow\n\n1. **Initial Auth**: Exchange cldkctl token for JWT\n2. **Token Caching**: JWT stored locally with 24-hour expiry\n3. **Auto-Reauth**: Automatically re-authenticate when token expires\n4. **Environment Persistence**: Remember which environment works\n\n## Example Usage\n\n### Basic Authentication\n```python\n# Authenticate (auto-fallback if production fails)\nauth(token=\"cldkctl_your_token_here\")\n\n# Check status\nstatus()\n```\n\n### Project Management\n```python\n# List all projects\nproject_list()\n\n# Get specific project details\nproject_detail(project_id=\"your_project_id\")\n```\n\n### Kubernetes Operations\n```python\n# List pods in default namespace\nk8s_pods(project_id=\"your_project_id\")\n\n# List deployments in specific namespace\nk8s_deployments(project_id=\"your_project_id\", namespace=\"kube-system\")\n```\n\n### Billing Queries\n```python\n# Get daily costs\nbilling_daily_cost(project_id=\"your_project_id\")\n\n# Get billing history\nbilling_history(\n project_id=\"your_project_id\",\n start_date=\"2024-01-01\",\n end_date=\"2024-01-31\"\n)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Authentication Failed**\n- Check your `CLDKCTL_TOKEN` is valid\n- Ensure token starts with `cldkctl_`\n- Try using staging environment manually\n\n**Production Database Error**\n- This is normal - the server auto-fallbacks to staging\n- Check status to see which environment is active\n\n**Token Expired**\n- The server auto-reauthenticates\n- Check status to verify authentication\n\n**Environment Issues**\n```python\n# Force staging environment\nauth(token=\"your_token\", force_staging=True)\n\n# Check current environment\nstatus()\n```\n\n## Version History\n\nCurrent version: 1.0.0 (Production)\n\n## License\n\nMIT License\n\n---\n\n## Security\n\n**Never commit your real tokens, secrets, or credentials to the repository.**\nAll authentication is handled via environment variables or user input. Example tokens in this documentation are placeholders only.\n\n--- ",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Cloudeka cldkctl CLI integration with automatic environment fallback (Testing Version)",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/cloudeka/mcp-cldkctl#readme",
"Homepage": "https://github.com/cloudeka/mcp-cldkctl",
"Issues": "https://github.com/cloudeka/mcp-cldkctl/issues",
"Repository": "https://github.com/cloudeka/mcp-cldkctl"
},
"split_keywords": [
"cldkctl",
" cli",
" cloud",
" cloudeka",
" kubernetes",
" mcp",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f40ef2c37bde0d80476a253c86ec98d34a51dafeea99cd0f23235abd5644a3c",
"md5": "edd41591677a11979afc10f8eb7bf796",
"sha256": "43faf8fc9d535ef3678627800e60cf53a7f2d4d1390d8e27abd41b361b92cd2c"
},
"downloads": -1,
"filename": "mcp_cldkctl-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "edd41591677a11979afc10f8eb7bf796",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15058,
"upload_time": "2025-07-14T02:56:57",
"upload_time_iso_8601": "2025-07-14T02:56:57.129302Z",
"url": "https://files.pythonhosted.org/packages/4f/40/ef2c37bde0d80476a253c86ec98d34a51dafeea99cd0f23235abd5644a3c/mcp_cldkctl-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "45072ee3c33282025387c8a372539f84a4fe95d1eae8492ae96ead1873fe87b2",
"md5": "5ddbed79f9827613dd85fddb2aca8c96",
"sha256": "540579f17cd12468e11d04efba8c204714af94d3f026ab77bcabf50c31cbb63e"
},
"downloads": -1,
"filename": "mcp_cldkctl-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "5ddbed79f9827613dd85fddb2aca8c96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 54864,
"upload_time": "2025-07-14T02:56:59",
"upload_time_iso_8601": "2025-07-14T02:56:59.062603Z",
"url": "https://files.pythonhosted.org/packages/45/07/2ee3c33282025387c8a372539f84a4fe95d1eae8492ae96ead1873fe87b2/mcp_cldkctl-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 02:56:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloudeka",
"github_project": "mcp-cldkctl#readme",
"github_not_found": true,
"lcname": "mcp-cldkctl"
}
