homelab/platform/mcp-servers/README.md

MCP Umbrella Helm Chart

Complete deployment solution for the MCP (Model Context Protocol) server ecosystem. This umbrella chart deploys all MCP servers with a central gateway for unified access.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         MCP Gateway                              │
│                    (LoadBalancer Service)                        │
│              http://<LoadBalancer-IP>:3000                       │
│                                                                   │
│  Routes requests to individual MCP servers:                      │
│  POST /mcp/n8n-mcp        → n8n-mcp:3001                        │
│  POST /mcp/playwright-mcp → playwright-mcp:3002                 │
│  POST /mcp/kubernetes-mcp → kubernetes-mcp:3003                 │
│  POST /mcp/github-mcp     → github-mcp:3004                     │
│  ... (all 13 MCP servers)                                        │
└─────────────────────────────────────────────────────────────────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
   │  n8n-MCP │  │Playwright│  │Kubernetes│  │ GitHub   │
   │  :3001   │  │   MCP    │  │   MCP    │  │   MCP    │
   │          │  │  :3002   │  │  :3003   │  │  :3004   │
   └──────────┘  └──────────┘  └──────────┘  └──────────┘
                        ... (9 more servers)

   ┌──────────────────────────────────────────────────────┐
   │             Memory MCP (Central State)                │
   │              :3013 → Redis/PostgreSQL                 │
   │   Provides shared state for all MCP servers          │
   └──────────────────────────────────────────────────────┘

Features

• 13 MCP Servers available for automation
• Central Gateway with API key authentication
• LoadBalancer access to entire MCP ecosystem
• Memory-MCP as central coordinator for shared state
• Selective Deployment - enable only the servers you need
• Production-Ready with RBAC, security contexts, and health checks
• Auto-Scaling for gateway and resource-intensive servers

Quick Start

1. Prerequisites

# Ensure you're in the right directory
cd /data/data/com.termux/files/home/git/mcp-servers/mcp-umbrella

# Build chart dependencies
helm dependency build

2. Generate API Keys

# Generate secure API keys for the gateway
echo "n8n API key: $(openssl rand -hex 32)"
echo "admin API key: $(openssl rand -hex 32)"

3. Configure Required Secrets

Create a custom-values.yaml file:

mcp-gateway:
  gateway:
    auth:
      apiKeys:
        - name: "n8n"
          key: "YOUR_N8N_API_KEY_HERE"
        - name: "admin"
          key: "YOUR_ADMIN_API_KEY_HERE"

n8n-mcp:
  n8nMCP:
    n8n:
      apiKey: "YOUR_N8N_INSTANCE_API_KEY"

github-mcp:
  github:
    token: "YOUR_GITHUB_TOKEN"
    owner: "your-github-username"

4. Deploy

# Create the mcp namespace
kubectl create namespace mcp

# Install the umbrella chart
helm install mcp-ecosystem . \
  --namespace mcp \
  -f custom-values.yaml

5. Verify Deployment

# Check all pods
kubectl get pods -n mcp

# Get gateway LoadBalancer IP
kubectl get svc -n mcp mcp-ecosystem-mcp-gateway

# Test health endpoint
GATEWAY_IP=$(kubectl get svc -n mcp mcp-ecosystem-mcp-gateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
curl http://$GATEWAY_IP:3000/health

MCP Servers Included

Server	Port	Status	Description
mcp-gateway	3000	Always Enabled	Central routing gateway
n8n-mcp	3001	Enabled	n8n workflow automation
playwright-mcp	3002	Enabled	Browser automation
kubernetes-mcp	3003	Enabled	Kubectl operations
github-mcp	3004	Enabled	GitHub API operations
postgresql-mcp	3005	Disabled*	PostgreSQL operations
sqlite-mcp	3006	Enabled	SQLite operations
prometheus-mcp	3007	Disabled*	Metrics queries
slack-mcp	3008	Disabled*	Slack operations
s3-mcp	3009	Disabled*	S3/MinIO operations
filesystem-mcp	3010	Enabled	File operations
puppeteer-mcp	3011	Disabled*	Chrome automation
fetch-mcp	3012	Enabled	HTTP requests
memory-mcp	3013	Enabled	Central state coordinator

*Requires additional configuration - see Configuration section

Configuration

Enabling/Disabling Servers

In your custom-values.yaml:

# Enable a disabled server
prometheus-mcp:
  enabled: true
  prometheus:
    url: "http://your-prometheus-server"

# Disable an enabled server
playwright-mcp:
  enabled: false

Configuring the Gateway

mcp-gateway:
  service:
    type: LoadBalancer
    loadBalancerIP: "192.168.1.100"  # Optional static IP

  ingress:
    enabled: true  # Enable Ingress (currently disabled)
    hosts:
      - host: mcp.caffeinetux.com
        paths:
          - path: /
            pathType: Prefix

  autoscaling:
    enabled: true
    minReplicas: 1
    maxReplicas: 5

Configuring Memory-MCP Backend

Choose Redis or PostgreSQL:

memory-mcp:
  storage:
    backend: "redis"  # or "postgres"

  redis:
    host: "redis.default.svc.cluster.local"
    port: 6379
    password: "your-redis-password"

Usage Examples

From n8n Workflow

Use the HTTP Request node:

// n8n HTTP Request Node
Method: POST
URL: http://mcp-ecosystem-mcp-gateway.mcp.svc.cluster.local:3000/mcp/playwright-mcp
Authentication: Header Auth
Header Name: Authorization
Header Value: Bearer YOUR_N8N_API_KEY

Body:
{
  "jsonrpc": "2.0",
  "method": "navigate",
  "params": {
    "url": "https://example.com"
  },
  "id": 1
}

From External Client

# Get list of available servers
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  http://<LoadBalancer-IP>:3000/servers

# Make MCP request to Kubernetes-MCP
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "get_pods",
    "params": {"namespace": "default"},
    "id": 1
  }' \
  http://<LoadBalancer-IP>:3000/mcp/kubernetes-mcp

Store Shared State in Memory-MCP

# Store a value
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "memory_store",
    "params": {
      "namespace": "workflow",
      "key": "user_session",
      "value": {"user_id": 123, "state": "active"},
      "ttl": 3600
    },
    "id": 1
  }' \
  http://<LoadBalancer-IP>:3000/mcp/memory-mcp

# Retrieve the value
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "memory_retrieve",
    "params": {
      "namespace": "workflow",
      "key": "user_session"
    },
    "id": 2
  }' \
  http://<LoadBalancer-IP>:3000/mcp/memory-mcp

Upgrading

# Update dependencies
helm dependency update

# Upgrade the deployment
helm upgrade mcp-ecosystem . \
  --namespace mcp \
  -f custom-values.yaml

Uninstalling

# Remove the deployment
helm uninstall mcp-ecosystem --namespace mcp

# Optionally delete the namespace
kubectl delete namespace mcp

Troubleshooting

Gateway not accessible

# Check gateway pod logs
kubectl logs -n mcp -l app.kubernetes.io/name=mcp-gateway

# Check service
kubectl describe svc -n mcp mcp-ecosystem-mcp-gateway

MCP server not responding

# Check specific server logs
kubectl logs -n mcp -l app.kubernetes.io/name=playwright-mcp

# Check if server is registered in gateway
curl -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  http://<LoadBalancer-IP>:3000/servers

Authentication errors

# Verify API keys are set
kubectl get secret -n mcp mcp-ecosystem-mcp-gateway-auth -o yaml

# Test without auth (should fail with 401)
curl http://<LoadBalancer-IP>:3000/servers

Resource Requirements

Minimal Setup (5 servers)

• CPU: ~2 cores total
• Memory: ~3Gi total
• Storage: ~15Gi (PVCs for SQLite, Filesystem, Playwright)

Full Setup (all 13 servers)

• CPU: ~6 cores total
• Memory: ~10Gi total
• Storage: ~50Gi (with all persistence enabled)

Per-Server Resources

Server	CPU Request	CPU Limit	RAM Request	RAM Limit
Gateway	100m	500m	128Mi	512Mi
n8n-MCP	50m	200m	128Mi	256Mi
Playwright	200m	1000m	512Mi	2Gi
Kubernetes	100m	100m	128Mi	128Mi
Memory-MCP	100m	200m	256Mi	512Mi
Others	50-100m	100-200m	64-128Mi	128-256Mi

Security

• API Key Authentication on gateway
• RBAC for Kubernetes-MCP cluster access
• Secrets for all credentials (GitHub tokens, database passwords, etc.)
• Non-root users in all containers
• Read-only root filesystem where possible
• Network policies (add custom NetworkPolicy resources as needed)

Advanced Configuration

Custom n8n Node

See n8n-mcp-node/README.md for installing a custom n8n node that simplifies MCP gateway access.

Monitoring

# Enable Prometheus monitoring
prometheus-mcp:
  enabled: true
  prometheus:
    url: "http://prometheus-server.prometheus.svc.cluster.local"

High Availability

mcp-gateway:
  replicaCount: 3
  autoscaling:
    enabled: true
    minReplicas: 3
    maxReplicas: 10

Support

For issues or questions:

• Check the individual MCP server READMEs in ../*/README.md
• Review logs: kubectl logs -n mcp <pod-name>
• GitHub Issues: https://github.com/modelcontextprotocol/servers

License

See individual MCP server repositories for their respective licenses.