castai-mcp-server 0.2.1

Model Context Protocol server for CAST.AI - manage Kubernetes clusters via natural language

CAST.AI MCP Server

Model Context Protocol (MCP) server for the CAST.AI API. This server enables Claude Desktop and other MCP clients to interact with your CAST.AI Kubernetes clusters through natural language.

Features

• 5 Cluster Management Tools:

  • list_clusters - List all your Kubernetes clusters
  • get_cluster_details - Get detailed information about a specific cluster
  • get_cluster_policies - View cluster policies and configuration
  • get_cluster_score - Get cluster optimization score
  • get_cluster_score_history - View historical cluster score data

• Simple Authentication: API key-based authentication (no OAuth complexity)

• Local Only: Works with Claude Desktop via stdio transport

• Cluster Name Resolution: Use either cluster UUID or friendly cluster name

Prerequisites

• For npx installation (recommended): Node.js 16+ and uv
• For uvx installation: uv only
• For local development: Python 3.11+ and uv
• Always required: CAST.AI account with API access

Installation

Quick Start (Recommended) ⭐

The easiest way to use CAST.AI MCP Server - no installation or cloning required!

1. Get your CAST.AI API key:

• Visit console.cast.ai
• Navigate to Settings > API Keys
• Click Create API Key
• Choose Read-only access (recommended) or Full access
• Copy the generated API key

2. Configure Claude Desktop:

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "castai": {
      "command": "npx",
      "args": ["-y", "castai-mcp-server@latest"],
      "env": {
        "CASTAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Restart Claude Desktop

That's it! The server will be automatically downloaded and run when needed.

---

Alternative Installation Methods

Using uvx (Python package manager)

Requires: uv installed

{
  "mcpServers": {
    "castai": {
      "command": "uvx",
      "args": ["castai-mcp-server"],
      "env": {
        "CASTAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop.

Development / Local Installation

For local development or if you want to modify the code:

1. Clone the repository:

cd ~/repos
git clone https://github.com/castai/castai-mcp-external.git
cd castai-mcp-external

2. Install dependencies:

uv sync

3. Configure Claude Desktop:

{
  "mcpServers": {
    "castai": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/castai-mcp-external",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "CASTAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important: Replace /ABSOLUTE/PATH/TO/castai-mcp-external with the actual absolute path.

4. Restart Claude Desktop

Usage Examples

Once configured, you can interact with your CAST.AI clusters using natural language in Claude Desktop:

List all clusters

Show me all my Kubernetes clusters

Get cluster details

Get details for cluster "production-gke"

or

Show me information about cluster a1b2c3d4-e5f6-7890-abcd-ef1234567890

View cluster policies

What are the policies configured for my staging cluster?

Check cluster optimization score

What's the optimization score for my production cluster?

View score history

Show me the historical cluster score for my main cluster

Configuration

Environment Variables

• CASTAI_API_KEY (required) - Your CAST.AI API key from console.cast.ai
• CASTAI_API_URL (optional) - API endpoint URL (defaults to https://api.cast.ai)

Using a Different API Endpoint

If you're using a non-production CAST.AI environment, you can override the API URL:

{
  "mcpServers": {
    "castai": {
      "command": "uv",
      "args": ["--directory", "/path/to/castai-mcp-external", "run", "python", "main.py"],
      "env": {
        "CASTAI_API_KEY": "your-api-key-here",
        "CASTAI_API_URL": "https://api.dev-master.cast.ai"
      }
    }
  }
}

Troubleshooting

Authentication Errors

If you see a 401 authentication error:

1. Verify your API key is correct in claude_desktop_config.json
2. Check that the API key hasn't expired in the CAST.AI console
3. Ensure the API key has the necessary permissions
4. Restart Claude Desktop after making changes

Cluster Not Found

If you get a "Cluster not found" error:

• Verify you're using the exact cluster name as shown in CAST.AI console
• Alternatively, use the cluster UUID instead of the name
• Check that your API key has access to the cluster's organization

Server Not Starting

If the MCP server doesn't appear in Claude Desktop:

1. Check the Claude Desktop logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\Logs\mcp*.log
2. Verify the absolute path to castai-mcp-external is correct
3. Ensure uv is installed and in your PATH
4. Test the server manually:

   cd /path/to/castai-mcp-external
   export CASTAI_API_KEY="your-key"
   uv run python main.py
   

View Server Logs

To see detailed logs from the MCP server:

cd /path/to/castai-mcp-external
export CASTAI_API_KEY="your-key"
uv run python main.py

The server will output structured logs in logfmt format to stderr.

Security Best Practices

1. Use Read-Only API Keys: For safety, create API keys with read-only access unless you specifically need write permissions
2. Rotate API Keys Regularly: Periodically generate new API keys and update your configuration
3. Protect Your API Key: Never commit API keys to version control or share them publicly
4. Use Environment Variables: Always configure API keys via environment variables, not hardcoded in files

API Endpoints Used

This MCP server uses the following CAST.AI API endpoints:

• GET /v1/kubernetes/external-clusters - List clusters
• GET /v1/kubernetes/external-clusters/{id} - Get cluster details
• GET /v1/kubernetes/clusters/{id}/policies - Get cluster policies
• GET /v1/cost-reports/clusters/{id}/cluster-score - Get cluster score
• GET /v1/cost-reports/clusters/{id}/cluster-score-history - Get score history

Documentation

• CAST.AI API Documentation
• Model Context Protocol Documentation
• Claude Desktop Documentation

Support

For issues or questions:

• CAST.AI API Issues: [e-mail]
• MCP Server Issues: GitHub Issues

License

MIT License - see LICENSE file for details.