groupme-mcp-server
This server gives an AI assistant agentic tools to read and interact with a single GroupMe account's conversations.
List conversations – merge groups and DMs into one recency-sorted inbox with previews, member counts, and ids for chaining.
Read messages – page through a group or DM history, oldest first, with a cursor (
before_id/next_before_id) and optional concise or detailed formats.Get conversation context – fetch a group's metadata, member list, and recent messages in one call.
Search messages – search a conversation's history client-side by text and/or sender name, with honest reporting of scan limits.
Get highlights – see a group's most-liked messages and member summaries for a day, week, or month.
Send messages – post to a group or DM, optionally as a reply, optionally with a GroupMe-hosted image.
React to messages – like or unlike a specific message idempotently.
Provides tools for interacting with GroupMe, enabling listing conversations, reading and searching messages, fetching highlights, sending messages, and reacting to messages as the configured GroupMe account.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@groupme-mcp-server search for "weekend plans" in my family group"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
groupme-mcp-server
An MCP server for GroupMe, built with FastMCP.
It is a set of agentic tools, not an endpoint wrapper: instead of mirroring the GroupMe API v3 route-for-route, each tool does one job an assistant actually needs — merging groups and DMs into a single inbox, paginating history with cursors, searching client-side because GroupMe has no search endpoint, and reporting honestly when a result is truncated.
Status: early. Read, search/highlights, and the core write tools (sending messages, likes) are implemented; image upload is not yet.
Tools
Tool | What it does |
| Merge groups and DMs into one recency-sorted list with last-message previews. |
| Read one group or DM conversation, oldest first, with a |
| One group's metadata, member list, and recent messages in a single call. |
| Search a conversation's history client-side (GroupMe has no search API), with honest scan accounting. |
| A group's top-liked messages for a day/week/month plus a member summary. |
| Post to a group or DM, optionally as a reply or with a GroupMe-hosted image. |
| Like or unlike one message (ids from |
The read tools accept response_format: "concise" (default, human-readable)
or "detailed" (full ids and metadata).
Related MCP server: Teams MCP
Connecting to the hosted server
The server is deployed on Prefect Horizon at:
https://groupme.fastmcp.app/mcpThe deployment is protected by Horizon's built-in auth: clients sign in via OAuth, and only users the deployment owner has authorized can connect — unauthenticated requests are rejected. Note that this is a single-tenant deployment (see Security): every authorized client acts as the one GroupMe account whose token is configured on the server.
Running locally
The package runs as a stdio MCP server. Get a GroupMe access token from https://dev.groupme.com (sign in and copy your access token), then:
GROUPME_ACCESS_TOKEN=... uvx groupme-mcp-serverOr configure an MCP client to launch it:
{
"mcpServers": {
"groupme": {
"command": "uvx",
"args": ["groupme-mcp-server"],
"env": {
"GROUPME_ACCESS_TOKEN": "your-token-from-dev.groupme.com"
}
}
}
}Configuration
Everything is configured through environment variables (GROUPME_* may also
come from a local .env file — see .env.example).
Variable | Default | Description |
| (unset) | GroupMe API token from https://dev.groupme.com. Optional at startup; required when a tool calls the API. |
|
| Verbosity of the server's own loggers: |
|
| GroupMe REST API base URL (override mainly for testing). |
|
| GroupMe image-upload service base URL. Reserved: unused until image upload is implemented. |
| (unset) | OTLP/HTTP collector endpoint. Setting it turns tracing on. |
| (unset) | Extra headers for the OTLP exporter (e.g. |
|
| The |
| (unset) | Set to |
|
| Verbosity of FastMCP's own |
Security
Single-tenant by design. The server holds exactly one GroupMe token and every tool acts as that token's owner — reading their conversations, posting as them, liking as them. Anyone allowed to connect (locally, or through Horizon's auth on the hosted deployment) gets that full identity; there is no per-client GroupMe account mapping.
The token never crosses the MCP boundary. Clients never send or receive it: the token lives server-side, goes to GroupMe only as the
X-Access-Tokenrequest header (never in URLs), is excluded from tool output and error messages, and is registered for redaction if OTel header capture is enabled.Hosted-deployment caveat. On Horizon, tool requests and responses pass through Prefect's infrastructure and may appear in its request/payload logs. Message content read or written through the hosted server is visible to whoever operates the deployment; run the server locally if that is not acceptable.
Report vulnerabilities through private vulnerability reporting, not public issues — see SECURITY.md.
Observability
Logs are structured single lines on stderr (stdout would corrupt the stdio transport), each carrying the current OTel
trace_id/span_idwhen a span is active.GROUPME_LOG_LEVELcontrols the server's own loggers.Traces are opt-in: when
OTEL_EXPORTER_OTLP_ENDPOINTis set (andOTEL_SDK_DISABLEDis not truthy), the server installs an OTLP/HTTP span exporter. FastMCP emits a span for everytools/call, and outbound GroupMe HTTP requests get client spans via instrumentedhttpx2transports — without an endpoint everything no-ops.
Development
Requires uv and Python 3.13+.
git clone https://github.com/oddrationale/groupme-mcp-server.git
cd groupme-mcp-server
uv sync --all-groups
uv run lefthook install # install the git hooksCommon tasks:
Command | What it does |
| Format. |
| Lint and autofix. |
| Type check. |
| Run tests. Fails below 100% coverage. |
| Run a subset without the coverage gate. |
| Opt-in live/e2e suites (see |
| See what Horizon sees. |
Coverage is enforced at 100% (branch coverage included). If a line is
genuinely untestable, exclude it deliberately with # pragma: no cover and say
why in the PR — do not lower the threshold.
Deployment
The hosted server is deployed on Prefect Horizon, which builds directly from this repository via its GitHub App.
Entrypoint:
src/groupme_mcp_server/server.py:mcpDependencies: installed with
uv sync --frozen --no-dev, souv.lockmust be committed and current or the build failsEnvironment variables: registered in the Horizon UI (
GROUPME_ACCESS_TOKENat minimum)Auth: Horizon's built-in OAuth — clients must present a bearer token
The production target tracks main and deploys only after CI passes; every
pull request gets its own preview deployment. There is no deploy step in GitHub
Actions — CI gates quality and security, Horizon does the shipping.
Contributing
See CONTRIBUTING.md.
License
MIT © Dariel Dato-on
Available Tools
7 toolsget_conversation_contextGet Conversation ContextARead-onlyIdempotent
Get one group's metadata, member list, and recent messages in one call.
Use this to orient yourself in a group before reading further or
replying: it bundles what would otherwise take several calls. For
direct-message chats or for paging deeper into history, use
read_messages instead.
Inputs: group_id (required), response_format, recent_message_count. Returns: The result of ``get_conversation_context``. ``recent_messages`` is oldest first…
get_highlightsGet HighlightsARead-onlyIdempotent
Summarize what mattered in a group: its most-liked recent messages.
Use this to catch up on a busy group without reading everything: it wraps GroupMe's likes leaderboard into the period's top-liked messages (sender, like count, text preview) plus a per-member summary of who was most liked and most represented among them. The member summary covers only the leaderboard's messages, not the group's full history. The leaderboard endpoint is undocumented; if GroupMe has retired it, this tool fails with guidance rather than guessing.
Inputs: group_id (required), period, response_format. Returns: The result of ``get_highlights``: what mattered in one group. Built from GroupM…
list_conversationsList ConversationsARead-onlyIdempotent
List the user's GroupMe conversations, most recently active first.
Use this first, whenever you need to find a conversation or the ids the
other tools take: it merges groups and direct-message chats into one
recency-sorted list with last-message previews and member counts. Every
entry carries the group_id or other_user_id that read_messages
and get_conversation_context need.
Inputs: kind, limit, response_format. Returns: The result of ``list_conversations``: most recently active first.
react_to_messageReact To MessageAIdempotent
Like a GroupMe message, or remove your like from one.
Use this to react to a specific message on the authenticated user's
behalf — acknowledging something without posting a reply.
Both actions are idempotent: liking an already-liked message (or
unliking one you never liked) leaves it in the requested state. Ids come
from read_messages with response_format="detailed": use its
conversation_id (a group id, or a composite direct-chat id like
"123+456") and message id.
Inputs: action (required), message_id (required), conversation_id (required). Returns: Confirmation returned by ``react_to_message``.
read_messagesRead MessagesARead-onlyIdempotent
Read messages from one GroupMe conversation, oldest first.
Use this to read or page through the history of a specific group or
direct-message chat once you know its id (from list_conversations).
Sender names are resolved and attachments are normalized (image URLs,
reply/mention summaries). An empty page is a normal answer, not an
error: it means the conversation has no messages in the requested range.
Inputs: conversation (required), limit, since_id, before_id, +1 more. Returns: The result of ``read_messages``: oldest first. ``next_before_id`` is the oldest…
search_messagesSearch MessagesARead-onlyIdempotent
Search one conversation's message history for matching messages.
Use this to find specific messages ("who mentioned pizza?", "what did
Ada say last week?") instead of paging manually with read_messages.
GroupMe has no search API, so this scans backwards from the newest
message, matching query against message text and sender_name
against sender names (both case-insensitive substrings), until limit
matches are found, the oldest message is reached, or
max_messages_scanned messages have been examined. The result reports
exactly how far the scan got — check oldest_message_reached and
note before concluding something was never said.
Inputs: query (required), conversation (required), limit, sender_name, +2 more. Returns: The result of ``search_messages``: matches in scan order (newest first). The sc…
send_messageSend MessageA
Send a message to a GroupMe group or direct-message chat.
Use this to post as the authenticated user once you know where to send
(ids come from list_conversations). Each call sends a new message —
calling twice posts twice. To reply to a specific message, pass its id
(from read_messages) as reply_to_message_id.
Inputs: text (required), conversation (required), image_url, reply_to_message_id. Returns: Confirmation returned by ``send_message``. ``conversation_id`` is the id the re…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: search vs. paging vs. highlights vs. sending vs. reacting. The only mild overlap is read_messages vs. get_conversation_context, since both return recent messages, but the descriptions explicitly differentiate orientation-in-a-group from deep paging.
All seven tools follow a consistent snake_case verb_noun pattern (list_conversations, read_messages, get_conversation_context, search_messages, get_highlights, send_message, react_to_message). No style mixing or vague verbs.
Seven tools is well-scoped for a messaging integration, with discovery, reading, searching, summarizing, sending, and reacting each earning a place. Nothing feels redundant or bloated.
Covers the core lifecycle: find conversations, read, search, summarize, send, and react. Group or conversation creation, membership management, message deletion, and media sending are absent, but agents can work around these for typical read-and-post flows.
Maintenance
Related MCP Connectors
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Group chat for AI agents: 15 tools for messages, replies, approvals, joining and agent email.
Group chat for people and AI agents: read and send messages, files, polls, notes and boards.
Messaging infrastructure for AI agents across iMessage, WhatsApp, Telegram and SMS.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Microsoft 365 through the Microsoft Graph API, including searching Teams messages, managing chats, and sending messages.77 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with Microsoft Teams and Microsoft Graph through OAuth-authenticated tools for messaging, chat and channel management, message search, file uploads and downloads, and user directory lookups. Supports rich Markdown formatting, mentions, attachments, and LLM-friendly HTML-to-Markdown content conversion.12 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with Microsoft Teams and Microsoft Graph APIs for user and team management, channel and chat messaging, message editing and deletion, file upload/download, and advanced message search.12 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with Microsoft Teams and Microsoft Graph for messaging, chat and channel operations, user and team discovery, file uploads/downloads, and advanced message search.12 npmMIT