ClawQL

Kubernetes

ClawQL is usually deployed as clawql-mcp-http: Streamable HTTP MCP on /mcp, GraphQL on /graphql, and (when ENABLE_GRPC=1) gRPC protobuf MCP on port 50051—all in one pod. The Service exposes both HTTP and gRPC ports so clients can use localhost:50051 (Docker Desktop) or <LoadBalancer-ip>:50051 without kubectl port-forward. Docker Desktop defaults to the Helm chart (charts/clawql-mcp, values-docker-desktop.yaml); remote clusters often use Kustomize dev / prod with scripts/deploy-k8s.sh.

Local MCP on Docker Desktop

Use this when you want a stable URL (for example http://localhost:8080/mcp) for Cursor or other MCP clients, without running npx in a terminal.

Prerequisites

  • Docker Desktop with Kubernetes enabled (Settings → Kubernetes).
  • kubectl on your PATH. Helm 3 is required for the default install path only.
  • Repo clone at the version you want to run.

One-shot install

From the repository root:

make local-k8s-up

Or:

bash scripts/local-k8s-docker-desktop.sh

Default: helm upgrade --install with charts/clawql-mcp/values-docker-desktop.yaml: ghcr.io/danielsmithdevelopment/clawql-mcp:latest, LoadBalancer on 8080, default-multi-provider, hostPath vault at $HOME/.ClawQL (override CLAWQL_LOCAL_VAULT_HOST_PATH).

Kustomize: CLAWQL_LOCAL_K8S_INSTALLER=kustomize make local-k8s-up — kubectl apply -k docker/kustomize/overlays/local (no Helm). To build locally instead of GHCR, run CLAWQL_LOCAL_K8S_BUILD_IMAGE=1 make local-k8s-up (works with either installer).

Endpoints and client config

  • MCP (Streamable HTTP): http://localhost:8080/mcp
  • Health: curl -s http://localhost:8080/healthz

Point your MCP client at url (not stdio command). Example shape:

{
  "mcpServers": {
    "clawql": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Use your real host if you tunnel or expose the service elsewhere.

Optional gRPC on the same deployment

When ENABLE_GRPC=1 (and optionally ENABLE_GRPC_REFLECTION=1 for grpcurl list), the container listens on 50051 for grpc.health.v1, model_context_protocol.Mcp, and mcp.transport.v1.Mcp.Session. The clawql-mcp-http Service includes a grpc port (50051) alongside HTTP in the Helm chart and Kustomize base / dev / prod—verify with kubectl -n clawql get svc clawql-mcp-http. For native grpc readiness/liveness probes on kubelet 1.27+, use the opt-in overlay docker/kustomize/overlays/grpc-enabled/ (see root README Kubernetes section). Full port matrix: docs/deploy-k8s.md — Service ports.

What the Helm install sets

  • Namespace: clawql
  • CLAWQL_PROVIDER: default-multi-provider (Google top50 + Cloudflare + GitHub, same as bare npx clawql-mcp). Override via values-docker-desktop.yaml or helm --set provider=....
  • Kube context: the script prefers docker-desktop when present so you do not accidentally deploy to another cluster.

Cold start can take a while while specs load. Wait until /healthz returns {"status":"ok",...} or the pod is Ready before the client connects.

MCP auth tokens (GitHub, Cloudflare, Google)

For local Docker Desktop k8s, execute needs bearer tokens in the clawql-mcp-http pod. Per-vendor env vars match src/auth-headers.ts: GitHub (CLAWQL_GITHUB_TOKEN), Cloudflare (CLAWQL_CLOUDFLARE_API_TOKEN), Google (GOOGLE_ACCESS_TOKEN / CLAWQL_GOOGLE_ACCESS_TOKEN). The same GitHub PAT is stored as CLAWQL_BEARER_TOKEN for merged-bundle fallback.

One-shot: from the repo root, with gh logged in or values in .env:

bash scripts/k8s-docker-desktop-set-mcp-auth.sh

Pipe a PAT: gh auth token | bash scripts/k8s-docker-desktop-set-mcp-auth.sh. Set CLAWQL_LOAD_DOTENV=0 to skip sourcing .env.

This creates/updates Secret clawql-github-auth (name kept for backward compatibility), attaches keys to deployment/clawql-mcp-http, and restarts. Full table and manual kubectl steps: docker/README.md (section MCP auth). The old script name k8s-docker-desktop-set-github-token.sh is a deprecated alias.

helm upgrade --install reapplies chart values; env injected only with kubectl set env can be overwritten on the next upgrade. Prefer helm --set extraEnv or a Secret wired through values.yaml for durable config.

Rebuild after code changes

After you change the repo, either rebuild locally (CLAWQL_LOCAL_K8S_BUILD_IMAGE=1 make local-k8s-up) or pull a new GHCR tag and run helm upgrade with image.tag. Example recycle:

make local-k8s-up
kubectl --context docker-desktop -n clawql rollout restart deployment/clawql-mcp-http

Teardown

helm uninstall clawql -n clawql

Or delete the whole namespace:

kubectl --context docker-desktop delete namespace clawql

Remote clusters (dev / prod)

For registries and image tags (not the local latest flow), use overlays and the deploy script:

ENV=dev IMAGE=us-central1-docker.pkg.dev/<project>/<repo>/clawql-mcp TAG=<tag> make deploy-k8s

Or install the Helm chart with your image registry. Full checklist: docs/deploy-k8s.md.

More detail in the repo

  • Container build, Compose, and extended K8s notes: docker/README.md
  • Starter manifest: docker/kubernetes-starter.yaml

Was this page helpful?