talos-mcp-server

ry-ops/talos-mcp-server

3.2

If you are the rightful owner of talos-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Talos MCP Server provides seamless integration with Talos Linux clusters, enabling interaction through the native gRPC API.

Tools
12
Resources
0
Prompts
0

Talos MCP Server

An MCP (Model Context Protocol) server that provides seamless integration with Talos Linux clusters. This server enables Claude to interact with your Talos infrastructure through the native gRPC API.

Features

  • 🔧 Cluster Management: Get version info, health status, and resource information
  • 💾 Disk Management: List and inspect disks on Talos nodes
  • 📊 Monitoring: Access logs, services, and real-time dashboard data
  • 🔍 File System: Browse and read files on Talos nodes
  • 🔐 etcd Integration: Manage and inspect etcd cluster members
  • ☸️ Kubernetes Config: Retrieve kubeconfig for cluster access
  • 📡 Resource Inspection: Query any Talos resource (similar to kubectl get)

What is Talos Linux?

Talos Linux is a modern, secure, and immutable Linux distribution designed specifically for Kubernetes. Key features:

  • API-Managed: Completely managed via a declarative gRPC API (no SSH)
  • Immutable: Read-only root filesystem for enhanced security
  • Minimal: Only includes components necessary to run Kubernetes
  • Secure by Default: Kernel hardened following KSPP recommendations

Prerequisites

  1. Python 3.10+
  2. uv - Fast Python package installer
  3. talosctl - Talos CLI tool
  4. Talos Configuration - A valid talosconfig file (usually at ~/.talos/config)

Installation

1. Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

2. Install talosctl

# macOS
brew install siderolabs/tap/talosctl

# Linux
curl -sL https://talos.dev/install | sh

# Or download directly
curl -Lo /usr/local/bin/talosctl https://github.com/siderolabs/talos/releases/latest/download/talosctl-$(uname -s | tr "[:upper:]" "[:lower:]")-amd64
chmod +x /usr/local/bin/talosctl

3. Clone and Setup

cd talos-mcp-server

# Create virtual environment and install dependencies using uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
uv pip install -e .

Configuration

Talos Configuration

Ensure you have a valid Talos configuration file. This is typically created when you set up your Talos cluster:

# Generate config (if setting up new cluster)
talosctl gen config my-cluster https://<control-plane-ip>:6443

# Check your current config
talosctl config info

# View available contexts
talosctl config contexts

The MCP server will automatically use your default Talos configuration from ~/.talos/config.

Claude Desktop Integration

To use this MCP server with Claude Desktop, add it to your Claude configuration:

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

{
  "mcpServers": {
    "talos": {
      "command": "/path/to/talos-mcp-server/.venv/bin/python",
      "args": [
        "/path/to/talos-mcp-server/src/talos_mcp/server.py"
      ],
      "env": {
        "TALOSCONFIG": "/path/to/your/.talos/config"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Available Tools

Cluster Information

  • talos_config_info: Get current Talos configuration and context
  • talos_get_version: Get Talos Linux version from nodes
  • talos_health: Check cluster health status

Resource Management

  • talos_get_resources: Query any Talos resource (members, services, machineconfig, etc.)
  • talos_get_services: Get status of all services
  • talos_get_disks: List all disks on nodes
  • talos_dashboard: Get real-time resource usage snapshot

Logging & Debugging

  • talos_logs: Get logs from services or containers
  • talos_list: List files and directories on nodes
  • talos_read: Read file contents from nodes

etcd & Kubernetes

  • talos_etcd_members: List etcd cluster members
  • talos_get_kubeconfig: Retrieve kubeconfig for the cluster

Usage Examples

With Claude Desktop

Once configured, you can ask Claude natural language questions:

"Show me the version of Talos running on my cluster"

"What services are running on node 192.168.1.10?"

"Get the logs from kubelet on my control plane nodes"

"List all disks on 192.168.1.10"

"Check the health of my Talos cluster"

"Show me the etcd members"

Programmatic Usage

from talos_mcp.server import TalosClient

# Initialize client
client = TalosClient()

# Get context info
info = client.get_context_info()
print(info)

# Execute talosctl commands
result = await client.execute_talosctl(["version"])
print(result["stdout"])

Development

Running Tests

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=talos_mcp tests/

Code Quality

# Format code
black src/

# Lint code
ruff check src/

# Type checking
mypy src/

Architecture

┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │ MCP Protocol
         ↓
┌─────────────────┐
│  MCP Server     │
│  (Python)       │
└────────┬────────┘
         │ subprocess
         ↓
┌─────────────────┐
│   talosctl CLI  │
└────────┬────────┘
         │ gRPC + mTLS
         ↓
┌─────────────────┐
│  Talos Cluster  │
│   (apid API)    │
└─────────────────┘

Security Considerations

  1. mTLS Authentication: Talos API uses mutual TLS for authentication
  2. Certificate Management: Keep your talosconfig and certificates secure
  3. Network Access: Ensure your endpoints are properly firewalled
  4. Permissions: The MCP server has the same permissions as your talosconfig

Troubleshooting

talosctl not found

# Check if talosctl is in PATH
which talosctl

# Install talosctl if missing
curl -sL https://talos.dev/install | sh

Configuration not found

# Check config location
echo $TALOSCONFIG

# Verify config exists
ls -la ~/.talos/config

# Test connectivity
talosctl version

Connection refused

# Verify endpoints in config
talosctl config info

# Check network connectivity
ping <control-plane-ip>

# Verify certificates are valid
talosctl version --nodes <node-ip>

MCP Server Issues

# Test the server directly
python src/talos_mcp/server.py

# Check Claude Desktop logs
# macOS: ~/Library/Logs/Claude/
# Windows: %APPDATA%\Claude\logs\

Resources

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments