Skip to main content
Glama
groupme-mcp-server

groupme-mcp-server

by oddrationale

groupme-mcp-server

CI codecov OpenSSF Scorecard PyPI Python License: MIT Ruff

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

list_conversations

Merge groups and DMs into one recency-sorted list with last-message previews.

read_messages

Read one group or DM conversation, oldest first, with a next_before_id cursor.

get_conversation_context

One group's metadata, member list, and recent messages in a single call.

search_messages

Search a conversation's history client-side (GroupMe has no search API), with honest scan accounting.

get_highlights

A group's top-liked messages for a day/week/month plus a member summary.

send_message

Post to a group or DM, optionally as a reply or with a GroupMe-hosted image.

react_to_message

Like or unlike one message (ids from read_messages detailed format).

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/mcp

The 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-server

Or 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

GROUPME_ACCESS_TOKEN

(unset)

GroupMe API token from https://dev.groupme.com. Optional at startup; required when a tool calls the API.

GROUPME_LOG_LEVEL

INFO

Verbosity of the server's own loggers: DEBUG, INFO, WARNING, ERROR, or CRITICAL.

GROUPME_API_BASE_URL

https://api.groupme.com/v3

GroupMe REST API base URL (override mainly for testing).

GROUPME_IMAGE_API_BASE_URL

https://image.groupme.com

GroupMe image-upload service base URL. Reserved: unused until image upload is implemented.

OTEL_EXPORTER_OTLP_ENDPOINT

(unset)

OTLP/HTTP collector endpoint. Setting it turns tracing on.

OTEL_EXPORTER_OTLP_HEADERS

(unset)

Extra headers for the OTLP exporter (e.g. authorization=Bearer%20...).

OTEL_SERVICE_NAME

groupme-mcp-server

The service.name resource attribute on exported spans.

OTEL_SDK_DISABLED

(unset)

Set to true/1 to keep tracing off even when an endpoint is set.

FASTMCP_LOG_LEVEL

INFO

Verbosity of FastMCP's own fastmcp.* loggers.

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-Token request 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_id when a span is active. GROUPME_LOG_LEVEL controls the server's own loggers.

  • Traces are opt-in: when OTEL_EXPORTER_OTLP_ENDPOINT is set (and OTEL_SDK_DISABLED is not truthy), the server installs an OTLP/HTTP span exporter. FastMCP emits a span for every tools/call, and outbound GroupMe HTTP requests get client spans via instrumented httpx2 transports — 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 hooks

Common tasks:

Command

What it does

uv run ruff format .

Format.

uv run ruff check --fix .

Lint and autofix.

uv run ty check

Type check.

uv run pytest

Run tests. Fails below 100% coverage.

uv run pytest --no-cov -k name

Run a subset without the coverage gate.

uv run pytest -m integration --no-cov

Opt-in live/e2e suites (see tests/integration/).

uv run fastmcp inspect src/groupme_mcp_server/server.py:mcp

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:mcp

  • Dependencies: installed with uv sync --frozen --no-dev, so uv.lock must be committed and current or the build fails

  • Environment variables: registered in the Horizon UI (GROUPME_ACCESS_TOKEN at 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 tools
get_conversation_contextGet Conversation ContextA
Read-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 HighlightsA
Read-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 ConversationsA
Read-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 MessageA
Idempotent

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 MessagesA
Read-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 MessagesA
Read-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

    A4.4/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT