Beeper Personal MCP

A personal, self-hosted Model Context Protocol gateway for Beeper. Connect an assistant to the conversations already in your Beeper account: search, catch up, read attachments, and send messages with your approval.

Independent community project. Not affiliated with Beeper or Apple. Pre-release; one owner per installation. Your instance stays private even though this code is public. The GitHub Pages website introduces the project and offers a downloadable logo kit.

Start here

You need Node.js 20.19+ with npm, Git, and a Beeper account. Linux x86_64 is the validated deployment platform. The gateway is portable Node.js; the CLI and Beeper Server depend on their own OS support. Native Windows is not supported by the shell wrapper; use Linux/WSL.

git clone https://github.com/edouaz/beeper-personal-mcp.git
cd beeper-personal-mcp
./bin/setup

./bin/setup installs, configures and starts the project; on later runs use npm start. The setup assistant installs the gateway dependencies and runs the official Beeper CLI to install, sign in and verify your Beeper Server. It creates private credentials under state/. No manual .env editing is needed for a new installation. Your email/device verification still requires your participation.

Choose your connection:

./bin/setup --mode openai                         # private OpenAI tunnel; no app OAuth
./bin/setup --mode tunnel                         # temporary HTTPS; install cloudflared first
./bin/setup --mode remote --url https://mcp.example.com
npm run doctor                                   # local readiness checks
node cli/index.mjs connection                     # PRIVATE local client config, shown in terminal
./bin/beeper status                              # official Beeper CLI, isolated project state

Run one setup variant in a fresh checkout. For public remote and Cloudflare tunnel modes, save the owner password shown once by setup. The command launches the service; use npm start for subsequent launches. Public HTTP modes print an HTTPS MCP URL for OAuth; OpenAI mode prints the tunnel connection instructions. Availability of custom MCP connections depends on your client/account. See the complete installation guide, including client settings, stable tunnels, services, updates and migration.

Temporary tunnels change address on every start and are for development. This gateway uses JSON HTTP responses rather than SSE, which Quick Tunnels do not support. A remote ChatGPT connection cannot reach your computer’s localhost.

Related MCP server: agenticflow

What it does

• Search accounts, chats, contacts and messages; get unread conversations and resumable exports.

• Read bounded image/PDF attachments without giving the assistant arbitrary filesystem access.

• Use OAuth with PKCE, scoped access and owner approval for remote connections.

• Prepare a message for approval on a protected page before a single send attempt. Advanced direct-send mode is opt-in.

• Report pending, sent, delivered, read or failed from available evidence. An accepted send is not a delivery receipt.

• Support reactions, drafts, chat state, edit/delete and WhatsApp find-or-open where the connected network supports them; availability depends on the authorization mode.

See capabilities and test coverage. Local bearer mode exposes read tools and a local draft helper. Public HTTP writes require OAuth. Private OpenAI stdio mode offers direct writes only after an explicit opt-in; access is controlled by tunnel permissions. No bulk messaging, auto-replies or automatic send retries.

How it fits together

Local client ── bearer token ──┐
                              ├─ MCP gateway (127.0.0.1) ── Beeper Server ── your networks
ChatGPT ── HTTPS + OAuth ──────┘
           Caddy or tunnel

ChatGPT ── private OpenAI tunnel ── stdio gateway ── Beeper Server

The public code never includes your Beeper credentials, conversations, OAuth state or server binary. All runtime state belongs to you in state/. The optional event forwarder and plugin integration generator are included but not enabled by setup.

Development

npm ci
npm --prefix mcp ci
npm run check
npm test

Tests use mocks and a fake Beeper server. They do not access your account or send real messages. Live checks are separately gated; see CONTRIBUTING.md. CI checks syntax, tests, dependency audits and accidental private files on Node 20, 22 and 24.

Privacy, limits and license

Read the security model and security policy. Keep state/ private and back it up securely. Public HTTP OAuth callbacks currently support ChatGPT only. Private OpenAI tunnels use stdio with no app-level OAuth. Other local clients can use the bearer mode; the HTTP configuration format depends on the client. The CLI, website, documentation and approval pages use English by default. Duplicate/rate protections are in memory and reset at restart. One owner per instance; this is not a multi-user SaaS.

MIT applies to this repository. Beeper Server is proprietary software downloaded from Beeper by its official CLI; it is not redistributed here. Beeper, Apple and network names belong to their respective owners. The visual identity uses original artwork; see brand notes.

Troubleshooting · Changelog · Contributing