Ephemeral K8s

Release Build status codecov Commit activity License

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/docs/

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

Usage

Running the MCP Server

uvx mcp-ephemeral-k8s

Using the Library

import asyncio
from mcp_ephemeral_k8s import KubernetesSessionManager, presets

async def main():
    async with KubernetesSessionManager() as session_manager:
        mcp_server = await session_manager.create_mcp_server(
            presets.K8S_MCP_SERVER, wait_for_ready=True, expose_port=True
        )
        print(mcp_server.sse_url)

if __name__ == "__main__":
    asyncio.run(main())

Job 'mcp-ephemeral-k8s-proxy-1762291156-x17zuayy' in unknown state, waiting...
http://mcp-ephemeral-k8s-proxy-1762291156-x17zuayy.default.svc.cluster.local:8080/sse

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 MCP server

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

9. Visit the FastAPI server

   npx @modelcontextprotocol/inspector --sse http://localhost:8000/sse