Overview

Surfski is a small, self-hosted remote MCP server. You add it to Claude once as a custom connector. After that, Claude can search, read and draft email across several Gmail / Google Workspace mailboxes for each user, and users never see each other’s mailboxes.

• Works from claude.ai on the web, desktop and mobile. Any client that speaks MCP Streamable HTTP with OAuth works too.
• Each Claude user signs in with Google, and only allowlisted addresses get in.
• Each user links any number of mailboxes under short aliases such as work, personal or support.
• Drafts only today. Claude saves drafts and you send them from Gmail. Opt-in sending is on the roadmap.

Tools: list_accounts, link_account, relink_account, rename_account, unlink_account, search_threads, search_all_accounts, get_thread, get_message, list_labels, create_draft.

Why self-host?

Gmail’s read scopes are restricted scopes. To offer them to the public, an app needs Google OAuth verification plus a third-party CASA security assessment that is renewed every year. A self-hosted instance avoids all of that:

• you use your own Google Cloud project and OAuth client;
• an unverified app works for up to 100 users over the app’s lifetime, which is plenty for a person, family or small team;
• refresh tokens never leave your server.

The only cost is an “unverified app” warning on the Google consent screen. Your users click Advanced → continue once per mailbox.

How it works

Claude ─HTTPS─► your reverse proxy :443 ─► container :8000 (published on 127.0.0.1:38000)
                                           /mcp              MCP endpoint (bearer auth)
                                           /auth/callback    Google login for Claude users (layer A)
                                           /gmail/callback   Gmail mailbox linking (layer B)
                                           /healthz          returns "ok"
                                         volume → /data
                                           data.db           accounts (Fernet-encrypted refresh tokens), audit_log
                                           oauth/            FastMCP OAuth client storage (Fernet-encrypted)

There are two separate OAuth layers, and both use the same Google OAuth client:

Layer	Proves	Scopes	Redirect URI
A. MCP login	which Claude user is calling, checked against ALLOWED_USERS	openid, userinfo.email	https://<host>/auth/callback
B. Mailbox link	access to one mailbox	gmail.readonly, gmail.compose	https://<host>/gmail/callback

License

MIT

---

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