Kubearchive

A powerful FastMCP server for interacting with KubeArchive - the utility that stores Kubernetes resources off-cluster for long-term inspection and analysis.

Overview

KubeArchive is a utility that stores Kubernetes resources off of the Kubernetes cluster, enabling users to delete those resources from the cluster without losing the information contained in those resources. This MCP server provides a comprehensive interface to query, search, and analyze your archived Kubernetes resources through natural language interactions with AI assistants.

Features

• 🔍 Search & Query: Find archived resources by namespace, kind, name, or text search
• 📊 Resource History: Track the lifecycle and changes of specific resources over time
• 📈 Statistics & Analytics: Get insights into job success rates, resource distributions, and more
• 📤 Export Capabilities: Export archived resources in YAML or JSON formats
• 🔌 Flexible Connectivity: Support for custom KubeArchive endpoints
• 🚀 FastMCP Integration: Built on FastMCP for high performance and easy integration

Installation

Using pip

pip install kubearchive-mcp

From Source

git clone https://github.com/your-org/kubearchive-mcp.git
cd kubearchive-mcp
pip install -e .

Configuration

Environment Variables

• KUBEARCHIVE_ENDPOINT: KubeArchive API endpoint (default: http://localhost:8081)
• KUBEARCHIVE_TOKEN: Kubernetes service account token for authentication
• MCP_TRANSPORT: Transport protocol - stdio, http, or sse (default: stdio)
• MCP_HOST: Host for HTTP/SSE transport (default: 127.0.0.1)
• MCP_PORT: Port for HTTP/SSE transport (default: 8000)
• MCP_PATH: Path for HTTP transport (default: /mcp)

Example Configuration

export KUBEARCHIVE_ENDPOINT="https://kubearchive.your-cluster.com"
export KUBEARCHIVE_TOKEN="your-service-account-token"
export MCP_TRANSPORT="stdio"

Usage

As a Standalone Server

# Using STDIO transport (recommended for MCP clients)
kubearchive-mcp

# Using HTTP transport
MCP_TRANSPORT=http MCP_PORT=8000 kubearchive-mcp

# With custom KubeArchive endpoint and authentication
KUBEARCHIVE_ENDPOINT="https://kubearchive.example.com" \
KUBEARCHIVE_TOKEN="your-token" \
kubearchive-mcp

With MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "kubearchive": {
      "command": "kubearchive-mcp",
      "env": {
        "KUBEARCHIVE_ENDPOINT": "http://localhost:8081",
        "KUBEARCHIVE_TOKEN": "your-service-account-token"
      }
    }
  }
}

Other MCP Clients

Most MCP clients can connect using the STDIO transport. Refer to your client's documentation for configuration details.

Available Tools

Core Resource Management

• list_archived_resources - List archived resources with filtering options
• get_archived_resource - Get detailed information about a specific resource
• search_archived_resources - Search resources using query strings
• get_resource_history - Get historical timeline of a specific resource

Export & Analysis

• export_archived_resource - Export resources in YAML or JSON format
• get_archived_jobs_summary - Get Job statistics and success rates

Configuration

• configure_kubearchive_endpoint - Update the KubeArchive API endpoint
• configure_kubearchive_token - Set the Kubernetes service account token
• configure_kubearchive_auth - Configure both endpoint and authentication
• setup_kubearchive_auth - Create complete Kubernetes RBAC setup
• generate_auth_setup_script - Generate shell script for authentication setup
• verify_kubearchive_permissions - Verify service account permissions

Available Resources

• kubearchive://status - Check KubeArchive connection status
• kubearchive://stats - Get basic statistics about archived resources

Natural Language Examples

This server is designed to work with natural language. Here are some example queries you can use with AI assistants:

Basic Queries

• "List all archived resources in the production namespace"
• "Show me the details of the archived resource with ID abc123"
• "Search for all failed jobs from last week"

Historical Analysis

• "Get the history of the user-service deployment in the production namespace"
• "Show me the timeline of all pods that were named batch-job-*"

Statistics & Reporting

• "Give me a summary of job success rates for the last 30 days"
• "What types of resources are most commonly archived?"
• "Show me statistics for the data-processing namespace"

Export Operations

• "Export the resource abc123 to a YAML file"
• "Save the configuration of the failed job xyz789 to /tmp/debug.yaml"

Configuration & Authentication

• "Set the KubeArchive endpoint to https://archive.my-cluster.com"
• "Configure authentication with my service account token"
• "Set up Kubernetes RBAC for kubearchive-view service account"
• "Check the current status of the KubeArchive connection"
• "Verify permissions for my service account"

API Integration

The server integrates with KubeArchive's REST API endpoints:

• GET /api/v1/archived-resources - List resources
• GET /api/v1/archived-resources/{id} - Get specific resource
• GET /api/v1/search - Search resources

Development

Requirements

• Python 3.10+
• FastMCP 2.0+
• Access to a running KubeArchive instance

Setting up Development Environment

# Clone the repository
git clone https://github.com/your-org/kubearchive-mcp.git
cd kubearchive-mcp

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

# Run tests
pytest

# Run linting
black .
ruff check .
mypy .

Project Structure

kubearchive_mcp/
├── __init__.py          # Package initialization
├── main.py              # CLI entry point
└── server.py            # FastMCP server implementation

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (pytest)
6. Run linting (black . && ruff check . && mypy .)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• KubeArchive - The main KubeArchive project
• FastMCP - The FastMCP framework
• Model Context Protocol - The MCP specification

Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email Support

Acknowledgments

• Thanks to the KubeArchive team for creating such a useful tool
• Thanks to the FastMCP team for the excellent framework
• Thanks to the broader Kubernetes community