mcp-ephemeral-k8s 0.0.2

Python implementation to spawn ephemeral Model Context Protocol (MCP) servers using the kubernetes API.

mcp-ephemeral-k8s

A Python library for spawning ephemeral Model Context Protocol (MCP) servers on Kubernetes using Server-Sent Events (SSE).

• Github: https://github.com/BobMerkus/mcp-ephemeral-k8s/
• Documentation: https://BobMerkus.github.io/mcp-ephemeral-k8s/

Features

• Supports multiple runtimes:
  • Node.js (via npx)
  • Python (via uvx)
• Works with mcp-proxy for uvx or npx runtimes
• Supports both local kubeconfig and in-cluster configuration
• Can be run as MCP server
• Can be run as FastAPI server

Usage

Running the MCP Server

uvx mcp-ephemeral-k8s

Using the Library

from mcp_ephemeral_k8s import KubernetesSessionManager, presets

with KubernetesSessionManager() as session_manager:
    mcp_server = session_manager.create_mcp_server(presets.GITHUB, wait_for_ready=True)
    print(mcp_server.sse_url)

Installation

Prerequisites

• Docker
• Kind or any Kubernetes cluster with valid kubectl configuration

Option 1: Using uvx (Recommended)

uvx mcp-ephemeral-k8s

To connect to the MCP server, use the following config:

{
   "mcp-ephemeral-k8s": {
      "url": "http://localhost:8000/sse",
      "transport": "sse"
   }
}

Option 2: As a Python Package

pip install mcp-ephemeral-k8s
mcp-ephemeral-k8s

Option 3: Using Helm Chart

To install the Helm chart, run:

helm repo add mcp-ephemeral-k8s https://BobMerkus.github.io/mcp-ephemeral-k8s/
helm repo update
helm install mcp-ephemeral-k8s mcp-ephemeral-k8s/mcp-ephemeral-k8s

To upgrade the Helm chart, run:

helm upgrade -i mcp-ephemeral-k8s mcp-ephemeral-k8s/mcp-ephemeral-k8s

To install a specific version, run:

helm install mcp-ephemeral-k8s mcp-ephemeral-k8s/mcp-ephemeral-k8s --version <replace-with-version>

To uninstall the Helm chart, run:

helm uninstall mcp-ephemeral-k8s

Option 4: From Source

1. Clone the repository

   git clone https://github.com/BobMerkus/mcp-ephemeral-k8s.git
   cd mcp-ephemeral-k8s
   

2. Set up development environment

   make install
   

3. Run pre-commit hooks

   make check
   

4. Run tests

   make test
   

5. Build Docker images

   make docker-build-local
   make docker-build-local-proxy
   

6. Load images to cluster

   kind load docker-image ghcr.io/bobmerkus/mcp-ephemeral-k8s:latest
   kind load docker-image ghcr.io/bobmerkus/mcp-ephemeral-k8s-proxy:latest
   

7. Install Helm chart

   helm upgrade -i mcp-ephemeral-k8s charts/mcp-ephemeral-k8s --set image.tag=latest
   

8. Port forward the FastAPI server

   kubectl port-forward svc/mcp-ephemeral-k8s 8000:8000
   

9. Visit the FastAPI server

   open http://localhost:8000/docs