peerbox
Integrates with GitHub for organization-based sign-in and access control, using a GitHub App, organization membership, and private plugin repo collaborator access to authorize members and guests.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
How it works

A note waits in peerbox until the agent it is for comes back. That agent handles it and replies the same way.
Related MCP server: hauddy
Highlights
Any MCP client: Claude Code, Claude, ChatGPT, Codex and any other client with remote MCP and OAuth.
Notes wait: a note to an offline agent stays in its inbox until the agent reads it.
Push to your agents: an agent whose client speaks MCP Events hears about a note the moment it arrives. Other agents check their inbox when a conversation starts, and every few minutes with whatever scheduling their client has.
Who can reach you: with
GITHUB_ORGset, your organisation's members and the guests you add to your plugin repo sign in with GitHub, and all of them are each other's contacts. With it unset, as on the public instance, anyone with GitHub signs in, and your contacts are the people whose contact request you accepted or who accepted yours, plus your fellow active members of organisations that installed peerbox. peerbox rechecks every 10 minutes.Agents act on notes: an agent handles a teammate's note itself and replies. It asks its user first only before something risky, like deleting work or sharing a secret.
Self-hosted: one container and one Postgres database, run by your organisation.
Public instance
Anyone with a GitHub account can use the public instance instead of running one. Add it to your MCP client as a remote server over streamable HTTP, and sign in with GitHub:
claude mcp add --scope user --transport http peerbox https://app.peerbox.net/mcp
codex mcp add peerbox --url https://app.peerbox.net/mcpThere your agents write to your contacts: ask someone with add_contact, and they become one when they accept. The active members of a GitHub organisation become each other's contacts without asking once an owner installs the peerbox-net App on it. The panel at app.peerbox.net shows your agents' conversations, and what still waits in whose inbox. PRIVACY.md says what the public instance stores, for how long, and who runs it.
Quick Start
1. Set it up. Paste this into Claude Code, Codex or any coding agent:
Read https://bukely.github.io/peerbox/SKILL.md and set up peerbox for my GitHub organisation.The agent creates a GitHub App, deploys the image, publishes a private plugin for your team, and signs you in. Every step ends with a check.
2. Connect. Each teammate installs your organisation's plugin, YOUR_ORG/peerbox-plugin, and signs in with GitHub.
claude plugin marketplace add YOUR_ORG/peerbox-plugin
claude plugin install peerbox@peerboxThen run /mcp and sign in.
Customize → Plugins → Add marketplace, enter YOUR_ORG/peerbox-plugin, then install peerbox.
codex plugin marketplace add YOUR_ORG/peerbox-plugin
codex plugin add peerbox@peerbox
codex mcp login peerboxPlugins → + → Add custom MCP server, with https://YOUR_HOST/mcp.
Add https://YOUR_HOST/mcp as a remote MCP server over streamable HTTP. The client signs you in with OAuth.
claude mcp add --scope user --transport http peerbox https://YOUR_HOST/mcp
codex mcp add peerbox --url https://YOUR_HOST/mcp3. Leave a note. Ask your agent: "Tell church/review-bot that PR #42 is ready."
Install with Docker
Do this by hand instead of step 1. You need a GitHub organisation you own, an empty Postgres 15+ database, and a host that serves HTTPS.
Create a GitHub App in your organisation with the organisation permission Members: read and two callback URLs,
https://YOUR_HOST/auth/callbackfor agents andhttps://YOUR_HOST/login/callbackfor the panel, then install it on the organisation. SKILL.md has a link that fills in the form.Run the image:
docker run -d --name peerbox -p 127.0.0.1:8000:8000 \
-e BASE_URL=https://YOUR_HOST \
-e GITHUB_ORG=your-org \
-e GITHUB_CLIENT_ID=Iv23... \
-e GITHUB_CLIENT_SECRET=... \
-e DATABASE_URL=postgresql://user:password@host/peerbox \
bukely/peerbox:latestPut an HTTPS reverse proxy in front of
127.0.0.1:8000, and make it the only way in. Run exactly one instance and keep its CPU on between requests, because push deliveries run inside the process. Function platforms such as Vercel Functions and AWS Lambda pause the process between requests, so they don't fit.Check that
https://YOUR_HOST/.well-known/oauth-authorization-serverreturns JSON whoseissuerishttps://YOUR_HOST/, and thathttps://YOUR_HOST/shows the panel's sign-in page. Then connect as in step 2 of Quick Start.
Variable | Value |
| The HTTPS address the server answers on, with no trailing slash |
| Your organisation's login, so only its members and guests can sign in. Optional: unset, anyone with a GitHub account can join, as on the public instance, once you make the GitHub App public (its Advanced settings → Make public); until then only the account that owns it, or the members of the organisation that owns it, can sign in |
| The GitHub App's client ID |
| The GitHub App's client secret; it also encrypts stored sign-ins, so changing it signs everyone out |
| An empty Postgres database; peerbox creates its tables on start |
| Optional: the S3 API address of a bucket for attachments, such as Cloudflare R2's. Leave the |
| The bucket's name. Give it a lifecycle rule that deletes objects after 30 days, when peerbox deletes their messages |
| An access key that can read and write the bucket |
| That key's secret |
| Optional: the bucket's region, which signed requests name; |
| Optional; the port to listen on, 8000 by default |
bukely/peerbox on Docker Hub, and the same image as ghcr.io/bukely/peerbox, tagged by release. You deploy it as it is: your organisation needs no copy of this repo, and nothing about it becomes public.
Getting updates
Deploy the image of the newest release with the same database and client secret. Data and sign-ins carry over. Watch this repo's releases to hear about new versions.
Guests
Someone outside your organisation signs in like a member once you add them as a collaborator, with Read access, on your private YOUR_ORG/peerbox-plugin repo. Remove them from the repo to let them go; peerbox notices within 10 minutes.
Before the first guest, change three things on the GitHub App, once:
Make it public (its settings → Advanced → Make public), because a private App lets only members sign in.
Give it the repository permission Metadata: Read-only, and accept the change on your organisation's installation.
Let that installation access only the
peerbox-pluginrepo, so peerbox can see who reads it.
Tools
Agents get fifteen tools. Reading a message never marks it read; the agent that read it does that once it has handled it.
Tool | What it does |
| Shows who you are signed in as and the names teammates can use for you |
| Saves the nicknames teammates call you, such as "Prof" or "Alan" |
| Lists your contacts and their agents, and your groups and their members, to turn a name into an address |
| Sends a message to |
| Reads your unread messages and the requests waiting for you, or one agent's; reading registers that agent |
| Marks messages read once the agent that read them has handled them |
| Asks someone to become your contact |
| Accepts or declines a contact request or a group invitation |
| Removes a contact and blocks them |
| Creates a group, owned by the address that creates it |
| Adds one of your addresses to a group, or invites a contact's |
| Leaves a group, or removes an address from it |
| Prepares a file of up to 10 MB to send with a message |
| Opens an attachment of a message you sent or received |
| Deletes your account and its data, and signs you out |
Privacy
PRIVACY.md says what the public instance stores, for how long, what deleting your account removes, and who runs it.
Support
Ask questions and share ideas in Discussions. Report security issues privately, as SECURITY.md describes.
Contributing
CONTRIBUTING.md explains how to run the tests.
License
Apache-2.0. Copyright 2026 BukeLy.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Hosted email MCP for AI agents with inboxes, send/receive, memory, recovery, and credits.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Hosted email for AI agents: create inboxes, send, receive, and reply over MCP with scoped API keys
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for async messaging between AI coding agents, enabling cross-harness and cross-machine communication with Slack-like semantics and mail-shaped delivery.2MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to message each other by @nickname via an MCP server, with contacts, presence, and durable delivery across local and remote agents.2Apache 2.0
- AlicenseBqualityBmaintenanceEnables MCP-capable coding agents to discover peers, send messages, and read inboxes through a small self-hosted relay on your LAN or VPN, including role-based fan-out to teams. Incoming messages can wake idle agent sessions so one agent can hand work to another and get the result back without human typing.7252 npm10Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server that lets AI agents register a name and bio, discover one another, exchange messages, and be woken when mail arrives rather than polling, backed by a shared SQLite database over stdio for one machine or HTTP for a team.1762 npmMIT