lab-mcp

Remote MCP servers for Claude Cowork, hosted on the homelab.

Cowork only attaches remote MCP servers, and it reaches them from Anthropic's cloud over public HTTPS, whichever client you use. So every server here is a small web service on salvage: an app entry in the homelab repo's provision.yml, which turns into a quadlet behind Caddy, image pulled from GHCR. Each server is also its own OAuth 2.1 authorization server for Claude, delegating the actual login to Google and refusing every Google account but the listed ones.

Layout

packages/mcp_common   settings, Google login with the email allowlist, serving
servers/hello         the dummy server: `ping` and `whoami`
tests                 pytest; run with `uv run pytest`
Containerfile         one image for all servers; CMD picks the server

One uv workspace. Add a server as servers/<name> with a console script, register it in the root pyproject.toml, and give it an app entry in homelab.

Related MCP server: Remote MCP Server

Configuration

Everything is an environment variable, and anything missing stops startup with a message naming what to set. On the homelab the quadlet sets the first two and injects the rest as podman secrets.

Claude is pointed at <BASE_URL>/mcp. /healthz answers ok without a token.

Google OAuth client

One client serves every server in this repo. In Google Cloud Console:

1. Create a project, configure the consent screen as External and publish it. Only openid and email are requested, which needs no verification and, unlike Testing status, does not expire refresh tokens after seven days.

2. Create an OAuth client of type Web application. Add one redirect URI per server: https://hello-mcp.rce.fi/auth/callback, and http://localhost:8080/auth/callback for local runs.

Login-only scopes are allowed under Advanced Protection and by Workspace admins. Gmail and Drive scopes are not, unless the admin trusts the app; that is a separate decision for the servers that need them.

Deploying

Secrets first, once, from the homelab checkout. Each prompts for the value:

./set-secret.sh hello-mcp MCP_GOOGLE_CLIENT_ID
./set-secret.sh hello-mcp MCP_GOOGLE_CLIENT_SECRET
./set-secret.sh hello-mcp MCP_ALLOWED_EMAILS
head -c 48 /dev/urandom | base64 -w0 | ./set-secret.sh hello-mcp MCP_JWT_SIGNING_KEY

Then ./run-playbook.sh provision.yml. After that, pushing to main here runs the tests, pushes ghcr.io/rce/lab-mcp:main, and podman auto-update on salvage picks it up within five minutes.

In Claude: Settings, Connectors, Add custom connector, URL https://hello-mcp.rce.fi/mcp. It discovers the OAuth endpoints, registers itself, sends you through Google, and whoami should answer with your account.

Running locally

export MCP_GOOGLE_CLIENT_ID=...apps.googleusercontent.com
export MCP_ALLOWED_EMAILS=you@example.com
printf '%s' 'GOCSPX-...' > .local/google_client_secret
./scripts/run-hello.sh

Cowork cannot reach localhost, so this is for the OAuth endpoints and for an MCP client run by hand, e.g. the MCP Inspector.