Google Messages

Google Messages for web (messages.google.com/web) wrapped as a persistent-session macOS app and an MCP server, so you can text from a desktop window and let Claude send/read/search your messages.

How it works (and the one big caveat)

Google Messages has no official API. The only desktop interface is the phone-paired web client, so everything here drives that web page with Playwright. Practical consequences:

• ✅ Works for your own account and messages (personal automation).
• ⚠️ Fragile to UI changes — if Google changes the page HTML, selectors break. They live in one place: the SEL block in src/messages.mjs. Use the debug_snapshot tool to see what currently matches, then fix them.
• ⚠️ Your phone is still the SMS/RCS engine; the pairing expires after ~14 days of the phone being offline.

One persistent Chromium profile (in ~/Library/Application Support/google-messages-mcp/profile) holds your pairing, so you log in once. The same profile is both the app window and the automation target.

The profile can only be opened by one process at a time. When the MCP server is running, its headed window is your app — don't also run npm run app simultaneously.

Setup

npm install          # installs deps + the Chromium binary (postinstall)

First run — pair your phone

npm run app

A window opens showing a QR code. On your phone: Google Messages → menu → Device pairing → QR code scanner, scan it, and tick “Remember this computer.” The session now persists.

Use as an MCP server

Point your MCP client at the server. Example Claude Code / Claude Desktop config — replace /ABSOLUTE/PATH/TO with wherever you cloned this repo (run pwd in the repo root):

{
  "mcpServers": {
    "google-messages": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/google-messages-app/src/server.mjs"]
    }
  }
}

Note: The Messages web SPA has historically crashed or failed to render correctly under true headless Chromium. By default we run headed but make the window 100% invisible on macOS for automation (Garvis, MCP clients, etc.):

• Launch args: --window-position=-100000,-100000 --window-size=1,1 plus common suppression flags (--no-first-run, --disable-infobars, etc.).
• As soon as the browser context is created (and at 250ms + 700ms), AppleScript forces: visible of process = false, window to off-screen + tiny size, minimized, and not frontmost.

This keeps your persistent paired session working while preventing any visible window or navigation during tool calls / Garvis sweeps.

You can still force experimental true headless with GM_HEADLESS=true (or 1 or new) if you want to try, but success is not guaranteed.

Profile lock handling still applies (only one client can hold the profile). For Garvis the pkill + sleep logic is only active when not using the hidden-headed path.

Tools

Tool	What it does
pairing_status	Check if the session is paired; call first if others fail
list_conversations	Recent threads (name, snippet, unread)
read_conversation	Recent messages in a thread (by name)
send_message	Send to a contact name or raw phone number
search_messages	Search threads for a query
delete_conversation	Move a thread to Trash (recoverable) by exact name; refuses on ambiguity
debug_snapshot	Maintenance: dump selector match counts when the UI changes

Maintenance

When a tool returns empty/odd results, run debug_snapshot. If selector counts are 0, the UI changed — update the matching entry in the SEL block of src/messages.mjs.

License

GNU AGPL-3.0-or-later. Note the network-use clause: if you run a modified version of this software as a network service, you must make your modified source available to its users.