mkrasselt1/imap-mcp-server

•Updated 6 months ago

Multi-agent multi-user IMAP bridge with OAuth 2.1 for MCP (Claude.ai, etc.)

Image

1.2K

mkrasselt1/imap-mcp-server repository overview

⁠IMAP MCP Server

A multi-agent, multi-user HTTP IMAP bridge that acts as a remote MCP⁠ server with built-in OAuth 2.1 authorization. Designed to let AI agents (like Claude.ai) securely access email on behalf of users, with granular per-agent permission control.

⁠Features

MCP over Streamable HTTP — standard protocol that Claude.ai and other MCP clients speak natively
OAuth 2.1 Authorization Server — RFC 8414 discovery, RFC 7591 Dynamic Client Registration, PKCE-enforced flows
Multi-user / multi-agent — each user manages their own IMAP accounts; each agent connection gets its own scoped token
Granular permissions — users choose exactly which capabilities to grant each agent:
Scope Grants
mail:folders List mailbox folders
mail:read Read email messages
mail:search Search emails
mail:modify Move, flag, delete messages
mail:send Send emails via SMTP
Encrypted credential storage — IMAP/SMTP passwords encrypted with AES-256-GCM at rest
Connection pooling — IMAP connections are reused across tool calls with auto-disconnect on idle
Web dashboard — manage email accounts and revoke agent tokens

Scope	Grants
`mail:folders`	List mailbox folders
`mail:read`	Read email messages
`mail:search`	Search emails
`mail:modify`	Move, flag, delete messages
`mail:send`	Send emails via SMTP

⁠Quick Start with Docker

docker run -d \
  --name imap-bridge \
  -p 3000:3000 \
  -v imap-bridge-data:/app/data \
  -e BASE_URL=https://your-domain.com \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  mkrasselt1/imap-mcp-server

Or with Docker Compose:

git clone https://github.com/mkrasselt1/imap-mcp-server.git
cd imap-mcp-server
cp .env.example .env
# Edit .env with your values
docker compose up -d

⁠Environment Variables

Variable	Required	Description
`BASE_URL`	Yes	Public URL of the server (e.g. `https://mail.example.com`). Must be HTTPS for Claude.ai.
`PORT`	No	Listen port (default: `3000`)
`ENCRYPTION_KEY`	Yes	64-char hex string for AES-256-GCM encryption. Generate with `openssl rand -hex 32`
`SESSION_SECRET`	Yes	Random string for session cookies. Generate with `openssl rand -hex 32`

⁠Setup

⁠1. Deploy the server

Deploy behind a reverse proxy (nginx, Caddy, Traefik) with TLS. Claude.ai requires HTTPS.

⁠2. Create an account and add email credentials

Visit https://your-domain.com/signup and create an account
Go to the Dashboard and click Add Email Account
Enter your IMAP server details and credentials (use an App Password for Gmail/Outlook)
Optionally add SMTP settings for sending

⁠3. Connect from Claude.ai

Go to Claude.ai Settings > Integrations⁠
Click Add Custom Connector (or Add MCP Server)
Enter your server URL: https://your-domain.com/mcp
Claude.ai will automatically:
- Discover OAuth endpoints via /.well-known/oauth-authorization-server
- Register itself as an OAuth client (Dynamic Client Registration)
- Redirect you to the consent screen
On the consent screen, select which email account and permissions to grant
After authorizing, Claude.ai can use the email tools

⁠OAuth 2.1 Flow

Claude.ai                          IMAP Bridge                    User
   │                                    │                           │
   │  GET /.well-known/oauth-           │                           │
   │  authorization-server              │                           │
   │───────────────────────────────────>│                           │
   │  { endpoints, scopes }            │                           │
   │<───────────────────────────────────│                           │
   │                                    │                           │
   │  POST /oauth/register             │                           │
   │  { redirect_uris }                │                           │
   │───────────────────────────────────>│                           │
   │  { client_id }                    │                           │
   │<───────────────────────────────────│                           │
   │                                    │                           │
   │  Redirect to /oauth/authorize      │                           │
   │  + PKCE code_challenge             │                           │
   │───────────────────────────────────>│  Login form               │
   │                                    │──────────────────────────>│
   │                                    │  Username + password      │
   │                                    │<──────────────────────────│
   │                                    │  Consent screen           │
   │                                    │  (select account + perms) │
   │                                    │──────────────────────────>│
   │                                    │  Approve                  │
   │                                    │<──────────────────────────│
   │  Callback with auth code          │                           │
   │<───────────────────────────────────│                           │
   │                                    │                           │
   │  POST /oauth/token                │                           │
   │  + code_verifier (PKCE)           │                           │
   │───────────────────────────────────>│                           │
   │  { access_token, refresh_token }  │                           │
   │<───────────────────────────────────│                           │
   │                                    │                           │
   │  POST /mcp (tool calls)           │                           │
   │  Authorization: Bearer <token>    │                           │
   │───────────────────────────────────>│  IMAP                    │
   │  { tool results }                 │                           │
   │<───────────────────────────────────│                           │

⁠MCP Tools

Tool	Scope Required	Description
`list_folders`	`mail:folders`	List all mailbox folders
`list_messages`	`mail:read`	List messages with pagination
`read_message`	`mail:read`	Read full message by UID
`search_messages`	`mail:search`	Search by sender, date, subject, body
`move_message`	`mail:modify`	Move message between folders
`flag_message`	`mail:modify`	Set read/unread, star, delete flags
`send_mail`	`mail:send`	Send email via SMTP

⁠Development

npm install
npm run dev     # starts with tsx watch

npm run build   # compile TypeScript
npm start       # run compiled output

⁠Security Notes

HTTPS required for production — Claude.ai will not connect over plain HTTP
App Passwords — use app-specific passwords for Gmail, Outlook, etc. rather than your main password
Encryption key — keep your ENCRYPTION_KEY safe; losing it means stored IMAP passwords become unrecoverable
Token revocation — users can revoke agent tokens from the dashboard at any time
PKCE enforced — all OAuth flows require Proof Key for Code Exchange (S256)

⁠License

MIT

Tag summary

Recent tags

Content type

Image

Digest

sha256:fd3b79987…

Size

86.2 MB

Last updated

6 months ago

docker pull mkrasselt1/imap-mcp-server