Metadata-Version: 2.4
Name: castai-mcp-server
Version: 0.2.2
Summary: Model Context Protocol server for CAST.AI - manage Kubernetes clusters via natural language
Project-URL: Homepage, https://github.com/castai/castai-mcp-external
Project-URL: Documentation, https://github.com/castai/castai-mcp-external#readme
Project-URL: Repository, https://github.com/castai/castai-mcp-external
Project-URL: Issues, https://github.com/castai/castai-mcp-external/issues
Author-email: "CAST.AI" <support@cast.ai>
License: MIT
License-File: LICENSE
Keywords: castai,claude,kubernetes,llm,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/)
- **For uvx installation**: [uv](https://docs.astral.sh/uv/) only
- **For local development**: Python 3.11+ and [uv](https://docs.astral.sh/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](https://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:

```json
{
  "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

<details>
<summary><b>Using uvx</b> (Python package manager)</summary>

Requires: [uv](https://docs.astral.sh/uv/) installed

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

Restart Claude Desktop.
</details>

<details>
<summary><b>Development / Local Installation</b></summary>

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

1. **Clone the repository**:
```bash
cd ~/repos
git clone https://github.com/castai/castai-mcp-external.git
cd castai-mcp-external
```

2. **Install dependencies**:
```bash
uv sync
```

3. **Configure Claude Desktop**:
```json
{
  "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**
</details>

## 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:

```json
{
  "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:
   ```bash
   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:
```bash
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](https://api.cast.ai/v1/spec/#/)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/docs)

## Support

For issues or questions:
- CAST.AI API Issues: [support@cast.ai](mailto:support@cast.ai)
- MCP Server Issues: [GitHub Issues](https://github.com/castai/castai-mcp-external/issues)

## License

MIT License - see [LICENSE](LICENSE) file for details.
