[!IMPORTANT] Mailport is a security-preview project. Its architecture is designed for production use, but it is necessary to use your own vercel, db, bitwarden etc account because otherwise I can see your passwords 😅

Why Mailport

Most email integrations are built around one provider. Mailport provides a small, provider-independent MCP boundary for Gmail, Microsoft 365, iCloud, Yahoo, Aruba and any public IMAP/SMTP server with valid TLS.

• Credentials never enter the chat. Users add a mailbox through a short-lived HTTPS connection link.
• Passwords stay in a vault. IMAP and SMTP credentials are separate Bitwarden Secrets Manager secrets.
• Email stays ephemeral. Message bodies are fetched on demand and are not indexed or retained by default.
• Threads are model-ready. RFC headers, native provider IDs and conservative heuristics reconstruct useful conversations.
• Access is scoped. OAuth separates mail:read and mail:send; opaque account references prevent arbitrary mailbox selection.

MCP tools

Tool	What it does
accounts_list	Lists connected mailboxes using opaque references and masked addresses.
connection_link_create	Returns a 256-bit, single-use mailbox connection link valid for ten minutes.
threads_search	Searches bounded filters and reconstructs conversations across selected folders.
thread_get	Produces chronological, compact context with explicit omissions and truncation.
email_send_prepare	Returns the exact recipients, subject and body for explicit approval plus a five-minute token.
email_send_confirm	Sends only the unchanged, explicitly approved message and consumes the token once.

Sending is text-only in the initial release. It requires mail:send, an SMTP-enabled account, an exact preview and a separate explicit confirmation. Attachments are intentionally excluded.

How it works

flowchart TD
    C["ChatGPT or MCP client"] -->|"OAuth 2.1 + scoped token"| M["Mailport on Vercel"]
    U["User in secure connection page"] -->|"IMAP / SMTP credentials"| M
    M -->|"Secret IDs and metadata"| N["Neon Postgres"]
    M -->|"Encrypted credentials"| B["Bitwarden Secrets Manager"]
    M -->|"TLS, on-demand fetch"| P["Mail providers"]

ChatGPT never receives mailbox passwords, provider tokens or arbitrary IMAP access. Neon stores ownership and non-secret metadata; Bitwarden stores the credentials; Mailport fetches messages only when an authorized tool call needs them.

Thread intelligence

Mailport reconstructs a thread in a deterministic order:

1. Deduplicate copies using normalized RFC Message-ID values.
2. Join provider-native thread IDs within the same account.
3. Follow In-Reply-To and References relationships.
4. Optionally apply a conservative subject, participant and time heuristic.

Search expansion is bounded to two rounds. Compact context keeps the first message, matching anchors and the latest messages while removing repeated quoted history. Heuristic joins are returned with an explicit confidence label instead of being presented as certain.

Security boundaries

Boundary	Policy
Chat ↔ Mailport	OAuth 2.1, PKCE, audience validation and scoped access tokens.
User ↔ onboarding	Authenticated HTTPS page; fragment token; single use; ten-minute expiry.
Mailport ↔ Bitwarden	Dedicated machine account restricted to one Secrets Manager project.
Mailport ↔ providers	Verified TLS 1.2+, fixed ports, public-address validation and DNS-pinned sockets.
Mailport ↔ Neon	Pooled TLS connection; no mailbox password or message body persistence.
Email ↔ model	Email is untrusted data and cannot choose tools, accounts, scopes or recipients.

The application does not log passwords, OAuth tokens, subjects, message bodies, recipients or raw provider errors. See the complete security model.

Stack

• TanStack Start and React on the Vercel Node.js runtime.
• Official Model Context Protocol TypeScript SDK with stateless Streamable HTTP at /mcp.
• Better Auth email OTP and OAuth provider with PKCE, JWKS, consent and Dynamic Client Registration.
• Neon Serverless Postgres and Drizzle ORM.
• Bitwarden Secrets Manager official Node SDK.
• ImapFlow, PostalMime, html-to-text and Nodemailer.

Dependencies are pinned to exact versions and the lockfile is committed.

Quick start

Requirements: Node.js 22+, a Neon database, a Bitwarden Secrets Manager project and a Resend sender.

git clone https://github.com/eduardo-bolognini/mailport-mcp.git
cd mailport-mcp
npm install
cp .env.example .env.local

Fill .env.local, then run:

npm run db:migrate
npm run dev

The local application is available at http://localhost:3000; the MCP endpoint is http://localhost:3000/mcp. The full environment guide covers Neon, Bitwarden, Resend, Vercel and OAuth: docs/ENVIRONMENT.md.

Connect ChatGPT

After deploying and configuring the production environment:

1. Enable Developer mode in ChatGPT under Settings → Apps → Advanced settings.
2. Create a new app with the MCP URL https://your-domain.example/mcp.
3. Select OAuth authentication. Mailport exposes discovery and Dynamic Client Registration, so no ChatGPT client secret is required.
4. Sign in using the email code and grant Mailport read and send access once. A single mailbox setup link then configures IMAP and, when you enable it in the same form, SMTP. Every actual send still requires approval of the exact message preview.

Development

npm run typecheck
npm run check
npm test
npm run build

The test suite covers credential serialization, deterministic thread reconstruction and compact model context.

Project map

src/server/auth       Email OTP, OAuth and scoped token validation
src/server/mail       IMAP, SMTP, filtering, threading and context assembly
src/server/mcp        MCP tools and Streamable HTTP transport
src/server/secrets    Bitwarden Secrets Manager boundary
src/server/db         Neon and Drizzle schema
drizzle               Versioned database migrations
docs                  Architecture, security and protocol documentation

Roadmap

• Attachment metadata and opt-in bounded extraction.
• Provider OAuth adapters alongside app passwords.
• Admin security controls, credential rotation and mailbox revocation.
• Interoperability fixtures for additional MCP clients.

See the detailed roadmap.

Contributing

Security-minded contributions are welcome. Keep the gateway small, avoid credential or content persistence, and include tests for changes to authorization, filtering or threading behavior.

For vulnerabilities, follow SECURITY.md instead of opening a public issue.

License

Apache-2.0 © Eduardo Bolognini. See LICENSE.