Skip to main content
Glama
Sign In
grokbot-messages

grokbot-messages

by cahenesy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

grokbot-messages

A clean-room MCP connector for Google Messages for Web, intended for use as a Grok Bot plugin. Licensed Apache-2.0.

Status: pre-release, not yet tested against a live phone. Pairing and read-only listing are implemented per the spec; the first live run is pending. No send tools exist yet.

Google ToS / account risk. Automated access to Google Messages may conflict with Google's terms. Use only with your own account and phone. This project does not operate any shared or multi-tenant bridge.

Clean-room process

This code is written only from the spec team's handoff package in docs/handoff/, Google's public web client, and Google's Apache-2.0 UKEY2 library. The handoff README lists the clean-room rules, including the copyleft implementations and write-ups that must not be consulted. Every source used is logged in DEVLOG.md.

Questions for the spec team are filed as GitHub issues with the spec-question label. Answers come back as revisions to docs/handoff/SPEC.md / OPEN-QUESTIONS.md, never as code.

Related MCP server: mcp-gateway

Design choices

  • Pairing via a single-use page (owner direction, #14). start_pairing returns a short-lived, single-use link. You open it in your own browser and scan the QR code shown there with Google Messages → Device pairing → QR code scanner. The QR (which contains the long-lived payload keys) never appears in tool output, chat, or logs. The tools only return the link and a status. Pairing from a phone alone: open the link on any second screen (laptop, tablet, TV browser) and scan it with the phone. A camera-free option is under investigation (#16). Google may be retiring QR pairing in some regions; see #16.

  • Hosted use. On a per-user cloud host such as Grok Bot's, the encrypted session file and its passphrase live on the same machine. That protects against copies of the file, not against compromise of the host.

  • Fail on unknowns. Wherever the spec does not pin a wire detail, the code throws a SpecGapError naming the open question instead of guessing (src/protocol/specGaps.ts).

Layout

src/protocol/   protobuf binary + JSPB codecs, AuthMessage, pairing, RegisterRefresh (no I/O)
src/crypto/     payload AES-CTR+HMAC / AES-GCM, ECDSA P-256 device key (no I/O)
src/transport/  HTTPS calls to the Tachyon relay
src/session/    encrypted session store, refresh timing
src/mcp/        MCP stdio server (tools)
test/           unit tests against spec-defined layouts (no network)

Configuration

Variable

Purpose

${GOOGLE_MESSAGES_SESSION_PATH}

Path to the encrypted session file

${GOOGLE_MESSAGES_SESSION_KEY}

Passphrase (≥16 chars) used to encrypt the session file

${GOOGLE_MESSAGES_API_KEY}

Optional override. Normally read automatically from the public Messages web page

${GOOGLE_MESSAGES_PAGE_USER_AGENT}

Optional. That page only serves its config to a current desktop browser User-Agent. The connector sends a pinned one for this single public fetch (not for any relay call). Override it here if it goes stale

${GOOGLE_MESSAGES_PAIRING_BASE_URL}

Optional. HTTPS URL at which your browser reaches the pairing page (default: a local http://127.0.0.1 address, for running the connector on your own machine)

Self-hosting extras: GOOGLE_MESSAGES_PAIRING_BIND / GOOGLE_MESSAGES_PAIRING_PORT set the pairing page's listen address and port.

Advanced (self-hosted only): Google-account cookies

Not part of the normal setup. Google-account (emoji) pairing would need your Google web-session cookies. ⚠️ Those cookies grant broad access to your whole Google account, not just Messages. If this option is ever enabled, the cookies are kept only in memory and in the encrypted session file, never logged or returned, and signing out of the browser session they came from invalidates them. The protocol support is in src/session/googleAuth.ts. It is not wired into any tool yet (#15).

Never commit real values. The session file is encrypted with AES-256-GCM using a scrypt-derived key.

Tools

  • get_session_status — whether paired and when the token expires; never returns secrets.

  • start_pairing — returns {status, link, expiresAt} for the single-use pairing page.

  • get_pairing_status — waiting, paired, expired, failed or none.

  • list_conversations — recent conversations (25 per page; pass cursor for more). Read-only.

  • list_messages — messages in one conversation (50 per page; pass cursor for older). Read-only. Status codes are raw until their meanings are confirmed live.

Sending messages will require explicit per-message user confirmation: a send is first prepared, which returns a one-time code bound to the exact text, and only a matching confirm call executes it (src/mcp/confirm.ts).

Installing as a plugin

The repo is a Cursor-format plugin (.cursor-plugin/plugin.json + mcp.json), which Grok Bot's marketplace uses. The MCP server runs via npx -y github:cahenesy/grokbot-messages; set the plugin variables in the host's plugin configuration.

Development

npm install
npm test
npm run build

Requires Node.js 22+; CI and development use Node.js 24.

Spec gaps

Open questions that currently block functionality: see issues labelled spec-question.

Available Tools

1 tool
get_session_statusA

Report whether Google Messages is paired and when the auth token expires. Never returns secrets.

NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full behavioral burden. It usefully discloses that secrets/auth tokens are never exposed in the response, which is real value-add, but says nothing about auth requirements, failure behavior when unpaired, or whether the check is remote versus cached.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core purpose and followed by the security caveat. Every clause earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in to name the returned fields (paired state, token expiry), which covers the essentials for a zero-arg read tool. It stops short of documenting error or unpaired-state behavior, a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline is 4. No parameter-related text is needed or missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Report") and resource (session/auth status) plus the two concrete facts returned: pairing state and token expiry. With no siblings to distinguish from, it is fully self-explanatory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied only: an agent infers this is a diagnostic/preflight check to run before other Google Messages operations. There are no siblings or alternatives to route between, so no explicit when-to-use or when-not-to-use guidance is needed, but none is given either.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.0.1
    • First observedget_session_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 1 tool

Disambiguation5/5

There is only one tool, so there is no possibility of confusion or misselection between tools. Its purpose is clearly stated and distinct.

Naming Consistency5/5

The single tool uses a clear snake_case verb_noun pattern consistent with common MCP conventions. With only one name, there are no inconsistent naming styles to compare.

Tool Count2/5

For a server apparently focused on messages, one tool is far too few. A single status-check tool does not provide a meaningful operational surface.

Completeness1/5

The tool surface is severely incomplete for a messaging server. It only reports session status and lacks core operations such as sending, listing, reading, or managing messages.

Maintenance

ActivityNo data
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-gateway

    thargy
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables multiple MCP clients to securely access various third-party MCP backends through a single HTTP gateway, with modern MCP handshake compatibility and session lifecycle management.
    46 npm
    MIT

  • Model Context Protocol (MCP)

    akmalnurfauzii-dev
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables remote MCP connections with Google OAuth authentication, allowing secure access to MCP tools and resources.
    1
    MIT

  • WhatsApp MCP

    ionutsss1
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables MCP clients to read, search, and send personal WhatsApp messages and files through a locally linked device.
    37 npm
    MIT