Skip to main content
Glama
google-messages-for-web-mcp

google-messages-for-web-mcp

by whirlwin
README.md
# google-messages-for-web-mcp

An MCP server (stdio) that reads and sends messages in [Google Messages for web](https://messages.google.com/web/conversations) by driving your already logged-in Chrome tab through the `chromefile` CLI. Not affiliated with Google.

## Requirements

- macOS
- Chrome with [chromefile](https://github.com/whirlwin/chromefile) installed
- A Messages for web tab paired with your phone (one is opened in the background if missing, but pairing is up to you)
- Node >= 24

## Install

As a Claude Code plugin (registers the MCP server for you), inside Claude Code:

```
/plugin install google-messages-for-web-mcp --marketplace whirlwin/google-messages-for-web-mcp
```

On Claude Code versions without `--marketplace`, run `/plugin marketplace add whirlwin/google-messages-for-web-mcp` first, then `/plugin install google-messages-for-web-mcp`. Restart Claude Code and run the `status` tool.

Or as a plain MCP server:

```sh
npm install -g github:whirlwin/google-messages-for-web-mcp
claude mcp add --scope user google-messages -- google-messages-for-web-mcp
```

Set `CHROMEFILE_BIN` if `chromefile` is not on the `PATH` Claude Code sees. Leave `send_message` on per-call approval.

`dist/index.js` is a single esbuild bundle committed to git, because a plugin install copies the repo without running `npm install`. Run `npm run build` after changing `src/`; CI fails when `dist/` does not match.

## Tools

| Tool | Description |
|------|-------------|
| `status` | Is chromefile reachable, is a Messages tab open, is it ready or does it need pairing |
| `list_conversations` | `limit` (default 25): id, name, snippet, time, unread, pinned, muted (read only) |
| `read_messages` | `conversation_id`, `limit` (default 30): last messages in chronological order. Navigates the Messages tab to the conversation, which marks it read |
| `send_message` | `conversation_id`, `text` (max 2000 chars): types into the compose box, presses Enter (a trusted key event via CDP, since the app ignores synthetic clicks), returns `sent: true` once the new bubble appears (not confirmed delivery; see `status`). After an error that says the message may have been sent, do not retry |

## Security

- Incoming SMS and RCS text is untrusted input and can carry prompt injection. Every tool description says so.
- This server combines private data, untrusted content and an outbound send channel. Keep `send_message` behind per-call approval and never auto-approve it.
- Only one Messages for web session is active at a time. This server uses your existing tab and never clicks "Use here" or pairs for you; it returns an error telling you to do it.
- Conversation ids are validated against `^[A-Za-z0-9_-]+$` and all values reach the page as JSON literals, never as raw source.

## How it works

Each tool runs `chromefile call page.eval` against the Messages tab. Sending also uses `chromefile call page.cdp` to dispatch a trusted Enter key in the compose box. The functions in `src/page.ts` run inside the page and are serialised with `fn.toString()`. They rely on the app's `data-e2e-*` attributes and custom elements (`a[data-e2e-conversation]`, `mws-message-wrapper`, the compose box and send button). These selectors are reverse engineered and will break when Google changes the UI.

## Testing

```sh
npm test        # unit tests against a synthetic DOM fixture (happy-dom), no browser needed
npm run lint    # typecheck
```

End-to-end, against your real tab (not part of `npm test`):

```sh
GM_E2E_CONVERSATION=<conversation id> npm run test:e2e
GM_E2E_CONVERSATION=<conversation id> GM_E2E_SEND_TEXT="test" npm run test:e2e   # also sends a real message
```

## Alternatives

[openmessage](https://github.com/maxghenis/openmessage) talks to Google Messages at the protocol level (Go, via mautrix/gmessages libgm, AGPL-3.0) and needs no browser tab.

## License

MIT

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool maps to a distinct operation: health/readiness check, conversation listing, message reading, and message sending. There is no overlap between reading and sending, and the status tool is clearly separated as a preflight check. Boundaries are further reinforced by explicit guidance (e.g. call read_messages instead of retrying after ambiguous send errors).

Naming Consistency4/5

list_conversations, read_messages, and send_message follow a consistent verb_noun snake_case pattern. 'status' deviates as a bare noun, but it is short, conventional, and unlikely to be misread as a different convention.

Tool Count4/5

Four tools is a tight, well-scoped surface for bridging to a single web messaging UI, and each tool earns its place. It sits at the low end of the ideal range, but adding more tools would risk over-exposing an inherently limited automation surface.

Completeness3/5

The core lifecycle (check readiness, list, read, send) is covered, but notable gaps remain: no message/conversation search, no way to start a conversation with a number not already in the list, and no unread/read-state management. These gaps may force agents into dead ends for common tasks like texting a new contact.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues