cloudflare-dns-cloudflared-mcp

Architecture

Self-hosted MCP server for administering Cloudflare DNS and cloudflared tunnel services — expose SSH hosts, web UIs, and other services on your home network through Cloudflare Tunnels with Google OAuth access control.

Runs as a Docker container on your own infrastructure. Connects to Claude Code or any MCP-compatible client via bearer-token-authenticated HTTP.

Tools

DNS

Tunnels

Tunnel Services (workflow)

#### What service_expose_ssh and service_expose_web do

Each workflow tool wires up the full stack in one call:

1. Tunnel ingress rule — maps the public hostname to the private backend service
2. DNS CNAME — points subdomain.yourdomain.com → [tunnel-id].cfargotunnel.com
3. Cloudflare Access application — gates who can reach the service
4. Access policy — allows specific Google accounts, with optional one-time PIN (OTP) for non-Google emails

Prerequisites

Cloudflare Tunnel

You need a running cloudflared tunnel connected to your home network. Install cloudflared on your home server and connect it via the Cloudflare Zero Trust dashboard. The tunnel must show as Online before exposing services through it.

Google OAuth identity provider

For Google-authenticated access, configure Google as an identity provider once in the Zero Trust dashboard under Settings → Authentication. This is a one-time manual setup — the MCP server manages per-service access policies, not the identity provider itself.

Quick start

1. Clone

git clone [email protected]:andrewkriley/cloudflare-dns-cloudflared-mcp.git
cd cloudflare-dns-cloudflared-mcp

2. Configure

cp .env.example .env

Edit .env and fill in:

3. Run

docker compose up -d

Check it's healthy:

curl http://localhost:3000/health
# {"status":"ok"}

4. Connect Claude Code

Run once to register the server:

claude mcp add cloudflare-admin --transport http \
  --header "Authorization: Bearer YOUR_MCP_BEARER_TOKEN" \
  http://localhost:3000/mcp

Replace YOUR_MCP_BEARER_TOKEN with the value from your .env.

5. Example usage

Ask Claude:

"Expose my Proxmox server at 192.168.1.100:8006 as proxmox.yourdomain.com through my home tunnel. Allow access for [email protected]."

Claude will call dns_list_zones, tunnel_list, then service_expose_web to wire everything up.

Secrets & Security

Environment variables

All are loaded from .env via docker compose. The .env file is gitignored and must never be committed.

Creating the Cloudflare API token

Go to dash.cloudflare.com/profile/api-tokens and create a custom token with:

Set a 90-day expiry at creation time.

Token rotation (every 90 days)

1. Create a new token at dash.cloudflare.com/profile/api-tokens
2. Update CF_API_TOKEN in .env
3. Restart the container: docker compose restart
4. Delete the old token in the Cloudflare dashboard

Generating a bearer token

openssl rand -hex 32

Security controls

Development

Run locally without Docker

npm install
cp .env.example .env
# fill in .env
npm run dev

Build and test

npm run build          # compile TypeScript
npm run typecheck      # type-check without emitting
npm run lint           # ESLint
npm test               # unit tests (mocked, no credentials needed)
npm run test:integration  # integration tests (requires env vars — runs in CI)

Docker commands

docker compose up -d             # start in background
docker compose logs -f           # tail logs
docker compose restart           # restart after .env change
docker compose down              # stop and remove container
docker compose build --no-cache  # force rebuild image

CI

Every push and pull request runs:

All checks above are required for a PR to merge to main once enabled in branch protection. Pushing a tag v*.*.* runs the Release workflow (GitHub Release + GHCR image + latest git tag).

Known limitations

Browser-rendered SSH and short-lived certificates

service_expose_ssh sets up the correct server-side configuration for Cloudflare short-lived SSH certificates (TrustedUserCAKeys, AuthorizedPrincipalsFile, SSH CA). However, Cloudflare's browser-rendered SSH terminal uses libssh2 1.9.0, which does not support OpenSSH certificate authentication. Certificate support was added in libssh2 1.11.0 (2023).

Effect: When accessing an SSH service via the browser terminal, the browser prompts for a private key instead of logging in automatically with a short-lived cert.

Short-lived certs work correctly for native SSH client access via the cloudflared ProxyCommand:

Host ssh.yourdomain.com
  ProxyCommand cloudflared access ssh --hostname %h

Workarounds for browser-only access (e.g. when outbound SSH is blocked on the client network):

Option A — Enable password auth on the backend sshd. The SSH port is not publicly exposed (only reachable via the tunnel, gated by Cloudflare Access). Password auth behind Google OAuth is an acceptable trade-off:

# On the SSH backend host
sudo sed -i 's/^PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config
sudo systemctl reload ssh

Option B — Deploy a web terminal (wetty). Run wetty on the backend host and expose it as a web service. The browser connects to wetty over HTTPS; wetty connects to sshd on localhost. No libssh2 limitation applies.

docker run -d --restart unless-stopped \
  --name wetty \
  -p 3000:3000 \
  wettyoss/wetty --ssh-host localhost --ssh-port 22 --base /

Then expose via service_expose_web with backend_port: 3000, backend_protocol: http. Cloudflare Access gates access as normal.

Versioning

The canonical version is the root `VERSION` file (same pattern as splunk-lab). Run `npm run sync-version` to copy it into package.json. Pushing a tag v*.*.* triggers a GitHub Release and publishes the Docker image to GHCR.

See [VERSIONING.md](VERSIONING.md) for the full workflow, CI rules, and tag format.

Contributing

main is protected — all changes via PR from dev. CI must pass before merge. Direct pushes to main are blocked.