Quickstart (self-host)

You need a Linux host with Docker and Compose, a domain name, and a TLS reverse proxy such as Caddy, nginx or Traefik.

1. Google Cloud (one time)

1. Create a project and enable the Gmail API.
2. Google Auth Platform → Branding: set the app name, support email, home page, privacy policy link and authorized domain.
3. Audience: choose External, then click Publish app to move it to In production. Don’t submit it for verification. In Testing mode Google expires refresh tokens after 7 days, so you would have to relink weekly.
4. Data Access: add openid, .../auth/userinfo.email, .../auth/gmail.readonly and .../auth/gmail.compose.
5. Clients → create a Web application client with these redirect URIs:
   • https://<host>/auth/callback
   • https://<host>/gmail/callback
6. If you use Google Workspace, the admin should go to Admin console → Security → API controls → Manage third-party app access, add the app by client ID and mark it Trusted. Otherwise Workspace policy may block mailbox linking.

2. Configure

git clone <this repo> /opt/surfski && cd /opt/surfski

sudo install -d -m 700 /etc/surfski && sudo install -m 600 deploy/env.example /etc/surfski/env

python3 scripts/gen_secrets.py

Paste the four generated secrets into /etc/surfski/env, then fill in BASE_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and ALLOWED_USERS. The server refuses to start if any secret is missing or malformed.

Aliases: Google sign-in reports a user’s primary address. If your Workspace uses alias domains, put the primary addresses in ALLOWED_USERS. Linking an alias address links the primary mailbox behind it.

3. Run

sudo docker compose -p surfski up -d --build

curl -s 127.0.0.1:38000/healthz

Point your reverse proxy at 127.0.0.1:38000. deploy/Caddyfile.snippet is a Caddy example. Don’t enable response compression on this route, because the MCP stream uses SSE.

4. Connect Claude

In Claude, go to Settings → Connectors → Add custom connector and enter https://<host>/mcp. Click Connect and sign in with an allowlisted Google account. Then say: “link my work Gmail as work” and open the link Claude returns.

When you link a mailbox, sign in as that mailbox and tick both permission checkboxes.

Upgrade

git pull && sudo docker compose -p surfski up -d --build

Backups

Back up the surfski_surfski-data volume, for example with a nightly tar from a throwaway container. The backup is useless without TOKEN_ENCRYPTION_KEY and STORAGE_ENCRYPTION_KEY. Keep the env file in a separate place, such as a password manager, never in the same backup. If you lose the keys, users simply relink their mailboxes.

---

Synced from rayhu/surfski/README.md@e4c5de0. The repository is the source of truth.