Routes HTML form submissions to email, Telegram, webhooks, or CRMs through a centralized backend.
Also known as faahim/postbag, postbag, @postbag/mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Sep 21, 2026
- License
- AGPL-3.0
What is Postbag MCP?
Postbag routes HTML form submissions to email, Telegram, webhooks, or CRMs through a centralized backend.
Summary generated from the project's README
About Postbag MCP server
Postbag acts as a centralized backend for managing HTML form submissions across multiple websites. Instead of configuring individual destinations for every form, developers point their HTML forms to a Postbag endpoint. The system then routes that data to various destinations including email, Telegram, webhooks, or CRMs. This approach allows users to group many different forms into a single stream and map diverse input fields into a consistent data shape.
This MCP server is designed for developers and AI agents who manage numerous sites that need to feed data into downstream systems. It functions as a source of truth for form data and maintains a versioned contract between the collection point and the recipient. The architecture uses a database-first approach where every submission is recorded as a row to ensure data is never lost, even if event streams fail. Users interact with the service via the Postbag API, the postbag CLI, or the @postbag/sdk.
What you can do with it
- 1Consolidate multiple site formsRoute submissions from fifteen different websites into a single unified stream for a partner.
- 2Standardize diverse form dataMap different input fields from various forms onto one consistent data shape for downstream processing.
- 3Ensure reliable data deliveryGuarantee that form submissions arrive even if the real-time event system experiences an outage.
- 4Automate multi-channel notificationsSend form data to specific destinations like Telegram or a CRM automatically.
Written from the project's README. Every use case is checked against a quote from it.
How to install Postbag MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Postbag MCP in Claude Code
$ claude mcp add --env 'POSTBAG_API_KEY=<YOUR_POSTBAG_API_KEY>' postbag -- npx -y @postbag/mcpInstall Postbag MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"postbag": {
"command": "npx",
"args": [
"-y",
"@postbag/mcp"
],
"env": {
"POSTBAG_API_KEY": "<YOUR_POSTBAG_API_KEY>"
}
}
}
}Install Postbag MCP in VS Code
.vscode/mcp.json
{
"servers": {
"postbag": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@postbag/mcp"
],
"env": {
"POSTBAG_API_KEY": "<YOUR_POSTBAG_API_KEY>"
}
}
}
}Install Postbag MCP in VS Code CLI
$ code --add-mcp '{"name":"postbag","type":"stdio","command":"npx","args":["-y","@postbag/mcp"],"env":{"POSTBAG_API_KEY":"<YOUR_POSTBAG_API_KEY>"}}'Install Postbag MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"postbag": {
"command": "npx",
"args": [
"-y",
"@postbag/mcp"
],
"env": {
"POSTBAG_API_KEY": "<YOUR_POSTBAG_API_KEY>"
}
}
}
}Install Postbag MCP in Codex
$ codex mcp add postbag --env 'POSTBAG_API_KEY=<YOUR_POSTBAG_API_KEY>' -- npx -y @postbag/mcpInstall Postbag MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.postbag] command = "npx" args = ["-y", "@postbag/mcp"] [mcp_servers.postbag.env] POSTBAG_API_KEY = "<YOUR_POSTBAG_API_KEY>"
Install Postbag MCP in Gemini CLI
$ gemini mcp add -s user -e 'POSTBAG_API_KEY=<YOUR_POSTBAG_API_KEY>' postbag npx -- -y @postbag/mcpInstall Postbag MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"postbag": {
"command": "npx",
"args": [
"-y",
"@postbag/mcp"
],
"env": {
"POSTBAG_API_KEY": "<YOUR_POSTBAG_API_KEY>"
}
}
}
}Configuration
POSTBAG_API_KEYRequiredSecretA Postbag API key (pb_live_… or pb_test_…). Mint one at https://postbag.dev/app or with `postbag login`.
POSTBAG_API_URLBase URL of the Postbag API. Defaults to https://postbag.dev — set this only for a self-hosted instance.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablefaahim/postbag is public and reachablegithub.com/faahim/postbag ↗Pass
- Package names this repository as its source@postbag/mcp names faahim/postbag as sourcenpmjs.com/package/@postbag/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-21github.com/faahim/postbag ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @postbag/mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPostbag
A form backend that routes. Point any HTML form at a Postbag endpoint and it lands in your inbox — then goes wherever it should: email, Telegram, a webhook, a partner, your CRM. Built for people who run many sites, and for the AI agents that build them.
<form action="https://api.postbag.dev/s/fm_8f3kq2" method="POST">
<input name="email" type="email" required>
<textarea name="message"></textarea>
<button>Send</button>
</form>
That's the whole integration for one form. Everything else — grouping forty forms into one stream, mapping their different fields onto one shape, sending that shape to a partner between two dates, a daily digest, never losing a submission — is there when you need it and invisible when you don't.
New here (human or AI agent)? Read
CLAUDE.mdfirst.
Why it exists
Every website has forms. Every form needs somewhere to go. Formspree and friends solve "somewhere" for one site; they fall over when you have fifteen sites feeding one partner with fifteen slightly different forms. Postbag is the source of truth for what each form collects, what each downstream system receives, and the versioned contract between them.
The one idea
The database makes it correct; events make it fast.
A submission is accepted the instant it is a row. Delivery is a durable outbox that a
worker drains with retries. Realtime nudges are an accelerator, never a transport.
If every event stream in the system died, every submission would still arrive — late,
never lost. (Inherited from the lead pipeline this generalises; see
docs/ARCHITECTURE.md.)
Status
Phase 1 — MVP live at postbag.dev (site, docs, dashboard at
/app, API at /v1). See PROGRESS.md for the live blueprint and
docs/ROADMAP.md for phases.
Documentation
Start at docs/README.md.
License
The server, dashboard, site and domain packages (apps/*, packages/core, packages/db,
packages/auth) are licensed under AGPL-3.0. The client packages that run
inside your own code — @postbag/sdk, the postbag CLI and @postbag/mcp — are
MIT. Rationale in ADR-006.
Postbag MCP questions
How do I add Postbag MCP to Claude Code?
Run claude mcp add --env 'POSTBAG_API_KEY=<YOUR_POSTBAG_API_KEY>' postbag -- npx -y @postbag/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Postbag MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Where can form submissions be sent?
Submissions can be routed to email, Telegram, a webhook, a partner, or your CRM.
How do I integrate a form with Postbag?
You can integrate by pointing an HTML form's action attribute to a Postbag endpoint.
What makes Postbag different from other form services?
Postbag acts as a source of truth for form data and downstream system contracts, making it easier to manage multiple sites feeding into a single partner.