gmail-mcp

Exposes the Gmail tab open in your browser as MCP tools — no Gmail API, no OAuth. A browser extension reads the inbox with InboxSDK and acts on it by simulating the Gmail UI; a local bridge relays commands from any MCP client (e.g. Claude Code) to that tab.

MCP client (Claude)
   │ stdio
server/mcp.js        one per client session, forwards over HTTP
   │ POST /<command>  (Hono, port 8766)
server/bridge.js     single daemon
   │ WebSocket (port 8765)
extension            MV3, background ws client + content script
   │ InboxSDK / DOM
Gmail tab

Tools

Tool	What it does
list_visible_emails	Lists the thread rows currently rendered (subject, contacts, date, thread_id)
archive_thread	Archives a visible thread (row checkbox + toolbar button)
label_thread	Applies an existing label to a visible thread (row context menu)

Setup

1. Extension: cd extension && npm install && npm run build, then load extension/dist/ via chrome://extensions → Developer mode → Load unpacked. Open (or reload) Gmail.
2. Bridge: cd server && npm install && npm run bridge — keep it running.
3. MCP: claude mcp add gmail-mcp -- node <repo>/server/mcp.js, then start a new session.

Test without an MCP client:

curl -X POST localhost:8766/list_visible_emails
curl -X POST localhost:8766/archive_thread -d '{"thread_id":"..."}'

Limitations

• The Gmail tab must be open; only currently-rendered rows are visible to the tools.
• Actions simulate the UI: stable attributes are preferred (act="7", roles), but label_thread matches menu text and assumes an English Gmail UI. A Gmail redesign can break actions — the durable alternative is the official Gmail API.
• The bridge listens on localhost without auth; anything local can drive your Gmail tab. Don't expose the ports.
• InboxSDK telemetry is disabled (eventTracking / globalErrorLogging off).

Development

npm run lint / npm run format (Biome, 80 cols) from the repo root. New extension feature = one file in extension/src/features/ + one line in extension/src/content.js + a tool in server/mcp.js.