Skip to main content
Glama
cahenesy

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: Phase 1 in progress — not usable yet. Pairing is blocked on open spec questions (see Spec gaps). No send/read 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

  • Google-account (emoji) pairing is the primary path (owner ruling, issue #7). QR pairing is secondary and is not exposed as a tool: its payload contains the long-lived payload keys, so it must never pass through tool output or logs.

  • 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}

Relay API key; to be replaced by a runtime read of the page config (#3)

${GOOGLE_MESSAGES_GOOGLE_COOKIES}

Optional. Google web-session cookies, needed only for Google-account pairing

⚠️ Google cookies grant broad access to your whole Google account, not just Messages. Supply them only if you accept that. They are kept only in memory and in the encrypted session file, never logged or returned in tool output, and dropped after pairing where the protocol allows. Signing out of the browser session they came from invalidates them. If you don't want to share cookies, run the connector yourself (same package, locally or on your own server).

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

Tools (Phase 1)

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

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.

ParametersJSON Schema
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

ActivityMaintained
ResponsivenessResponsive

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.
    18 npm
    MIT

  • Model Context Protocol (MCP)

    akmalnurfauzii-dev
    A
    license
    Not graded
    quality
    B
    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.
    18 npm
    MIT