Helm deployment

Install Browser MCP on Kubernetes with PostgreSQL, HTTPS, and an existing secret.

Requirements and defaults

• Kubernetes, Helm 3, a dedicated namespace, and an ingress controller if exposing HTTP.
• One server replica only; the chart rejects other values and the default namespace.
• An existing Kubernetes Secret; the chart does not generate passwords or embed plaintext secrets in Helm release values.
• Bundled PostgreSQL stores its data on a 10Gi ReadWriteOnce volume from your cluster’s default StorageClass. To use a different class, set postgresql.persistence.storageClass before the first install; it cannot be changed afterwards. Alternatively, use external PostgreSQL.
• Chart 0.3.18 installs the public community 0.3.18 server image for Linux amd64 and arm64, whose tool guidance describes session-owned and shared downloads. Use matching CLI 0.3.18 for the private download routing fix. Native protocol 3, database schema, templates and configuration are unchanged.

Upgrade notice: internal pages, local files and the Browser MCP dashboard are no longer blanket-blocked, subject to Chrome’s own limits. Keep administrative sign-ins outside automated profiles unless deliberately delegated. See Security.

Add the chart repository and download the 0.3.18 chart:

helm repo add browser-mcp https://charts.browser-mcp.click
helm repo update
helm pull browser-mcp/browser-mcp --version 0.3.18

1. Prepare namespace and secrets

Create a dedicated namespace:

kubectl create namespace browser-mcp

Create browser-mcp-secrets in that namespace using your secret manager. It must contain DATABASE_URL, AUTH_SECRET, SETTINGS_ENCRYPTION_KEY, and, for bundled PostgreSQL, POSTGRES_PASSWORD. Generate passwords and keys independently; do not use example strings.

If importing from a protected local env file, keep it outside the repository, mode 0600, and never include export prefixes:

kubectl -n browser-mcp create secret generic browser-mcp-secrets \
  --from-env-file=/secure/path/browser-mcp.env

With release name browser and the default chart name, the bundled database’s service is browser-browser-mcp-postgres. Its connection string takes this shape, with a URL-encoded password:

postgresql://browser_mcp:<password>@browser-browser-mcp-postgres.browser-mcp.svc:5432/browser_mcp

DATABASE_URL must match postgresql.username, postgresql.database, and the password stored as POSTGRES_PASSWORD. A different release name or fullnameOverride changes the service name. The chart deliberately does not synthesize a secret database URL. Do not change the configured password expecting an initialized PostgreSQL PVC to rotate automatically.

2. Configure values

Save the following as values-production.yaml. Replace the hostname with your own and provide a TLS certificate in the browser-tls Secret. Set ingress.className to your ingress controller’s class, or omit it to use the cluster’s default IngressClass. Keep credentials out of this file:

secrets:
  existingSecret: browser-mcp-secrets
config:
  publicUrl: https://browser.example.com
ingress:
  enabled: true
  className: <your-ingress-class>
  host: browser.example.com
  tls:
    - secretName: browser-tls
      hosts: [browser.example.com]
postgresql:
  enabled: true
  persistence:
    storageClass: "" # Empty uses the cluster's default StorageClass.
    size: 10Gi

Point your hostname at the ingress controller. If HTTPS terminates at an upstream proxy instead, set ingress.tls: [] and keep config.publicUrl set to the external https:// origin. The chart does not issue certificates.

External PostgreSQL

Set postgresql.enabled: false. Put your external database’s URL into the same secret’s DATABASE_URL; no StatefulSet or PVC is then rendered. The database must already exist, be reachable from the migration and server pods, and permit schema migration. Configure verified TLS in the connection string according to your provider; do not disable certificate verification.

Private container images

The default community image is public. If you use a private image, create a kubernetes.io/dockerconfigjson Secret in the same namespace and reference it with imagePullSecrets: [{name: registry-pull}]. Do not put registry credentials in Helm values or source control.

3. Validate and install

Render the exact intended values and submit that rendered file to server admission before installation. The namespace must already exist for dry-run validation. The file contains secret references, not secret material.

helm lint ./browser-mcp-0.3.18.tgz --strict --namespace browser-mcp -f values-production.yaml
helm template browser ./browser-mcp-0.3.18.tgz --namespace browser-mcp \
  -f values-production.yaml > /tmp/browser-mcp-rendered.yaml
kubectl apply --dry-run=server -f /tmp/browser-mcp-rendered.yaml
helm upgrade --install browser ./browser-mcp-0.3.18.tgz --namespace browser-mcp \
  -f values-production.yaml --wait --wait-for-jobs --timeout 20m

Do not use helm template | kubectl apply as the upgrade mechanism: Helm release revisions identify migration jobs and prevent immutable Job updates. For an existing release, helm upgrade --dry-run=server additionally validates Helm’s actual release context. Fix all admission failures before proceeding.

Migration ordering

The chart waits for PostgreSQL, runs a database migration Job, and starts the server only after that Job completes successfully. If startup is blocked, inspect the migration Job and its logs.

Do not delete the current successful migration Job: restarted server pods need its completion record.

Upgrades use Recreate and interrupt active connections. Back up the database before upgrading, and check schema compatibility when choosing a version. Rolling back a chart or image does not undo database migrations.

4. Verify the release

kubectl -n browser-mcp get jobs,pods,pvc
kubectl -n browser-mcp rollout status statefulset/browser-browser-mcp-postgres --timeout=10m
kubectl -n browser-mcp rollout status deployment/browser-browser-mcp --timeout=20m
kubectl -n browser-mcp get events --sort-by=.lastTimestamp

Skip the StatefulSet check with an external database. Check the revision-named migration Job completed, Pods are Ready, the PVC is Bound, and the public /healthz and /readyz return success. Inspect migration/server logs without exposing secrets. Complete one browser pairing and a harmless MCP request before declaring the deployment usable.

Uninstalling the chart may retain StatefulSet PVCs. Manage backup and deletion explicitly; do not delete retained volumes as a routine troubleshooting step.