poke-mail

An MCP server that bridges IMAP/SMTP email accounts to Poke. Provides AI agents with tools to search, read, send, and manage emails, and automatically forwards new incoming emails to the Poke inbound endpoint.

Features

• 12 MCP tools: search, read, send, draft, archive, move, mark, list/create/rename/delete folders, server info
• Send toggle: Disable send_email globally or per account — agents use create_draft instead
• IMAP IDLE watcher: Real-time monitoring of new emails, forwarded to Poke automatically
• Multi-account support: Configure multiple email accounts in a single config file
• Bearer token auth: Secure the server with MCP_API_KEY so only you can use it
• No delete tool: Emails can be archived or moved, never deleted by an agent

Quick Start

Automated setup (recommended)

git clone https://github.com/kacperkwapisz/poke-mail.git
cd poke-mail

If you haven't logged into Poke yet, do that first — it lets setup.sh pick up your token automatically:

npx poke login

Then run the setup script:

bash setup.sh

setup.sh will:

1. Create a Python virtualenv and install dependencies
2. Detect your Poke API key from poke login credentials (or prompt you to paste one)
3. Copy config.example.yml → config.yml and inject the API key automatically
4. Generate a random MCP_API_KEY and write it to .env
5. Ensure the poke npm package is installed globally

After setup, open config.yml and fill in your email account credentials, then start the server:

./start.sh

AI coding agent setup

Copy this prompt into your AI coding agent (Claude Code, Cursor, etc.):

Set up poke-mail (https://github.com/kacperkwapisz/poke-mail) for me — clone the repo, run 'npx poke login' so I can authenticate with Poke (wait for me to confirm), then run 'bash setup.sh' which will automatically wire up my Poke API key, generate an MCP_API_KEY, and set up the virtualenv — then help me configure config.yml with my email credentials (guide me on IMAP/SMTP host and port for my provider but do NOT type passwords or secrets — tell me to enter those myself and confirm when done) — then run start.sh to start the server and tunnel it to Poke.

To start the server again later:

./start.sh

Manual Setup

1. Configure accounts

cp config.example.yml config.yml

Edit config.yml with your email credentials and Poke API key (from poke.com/settings/advanced):

webhook_url: https://poke.com/api/v1/inbound/api-message
poke_api_key: your-api-key  # from https://poke.com/settings/advanced

accounts:
  # iCloud Mail — login is @icloud.com, send as your custom domain
  - id: icloud
    imap_host: imap.mail.me.com
    imap_username: you@icloud.com
    imap_password: your-app-password
    smtp_host: smtp.mail.me.com
    smtp_username: you@icloud.com
    smtp_password: your-app-password
    from_address: you@yourdomain.com  # optional — override From: header
    watch_folders:
      - INBOX

  # Custom SMTP server
  - id: work
    imap_host: imap.example.com
    imap_username: you@example.com
    imap_password: your-password
    smtp_host: smtp.example.com
    smtp_username: you@example.com
    smtp_password: your-password
    watch_folders:
      - INBOX

For iCloud, generate an App-Specific Password.

2. Install dependencies

pip install -r requirements.txt

3. Run

MCP_API_KEY=your-secret-key python src/server.py

4. Test

npx @modelcontextprotocol/inspector

Open http://localhost:3000 and connect to http://localhost:3000/mcp using "Streamable HTTP" transport. Pass Authorization: Bearer your-secret-key header.

Authentication

Set MCP_API_KEY to secure the server. All requests must include Authorization: Bearer <MCP_API_KEY>.

If MCP_API_KEY is not set, the server runs unauthenticated (with a warning). Always set it in production.

When connecting from Poke, add the bearer token in your connection settings.

Docker

docker build -t poke-mail .

docker run -d \
  -p 3000:3000 \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  -e MCP_API_KEY=your-secret-key \
  poke-mail

Or use the pre-built image from GitHub Container Registry:

docker run -d \
  -p 3000:3000 \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  -e MCP_API_KEY=your-secret-key \
  ghcr.io/kacperkwapisz/poke-mail:main

Resource Limits

The server is mostly idle (IMAP IDLE + lightweight HTTP). Recommended limits for container orchestrators:

Resource	Reservation	Limit
Memory	128 MB	256 MB
CPU	0.25	0.5

MCP Tools

Tool	Description
search_emails	Search by from, to, subject, date range
read_email	Read full email content by UID
send_email	Send email with text/HTML, CC/BCC, reply threading (can be disabled)
create_draft	Save email as draft for review before sending
archive_email	Move email to Archive folder
move_email	Move email between folders
mark_email	Set read/unread/flagged/unflagged
list_folders	List all IMAP folders
create_folder	Create a new folder
rename_folder	Rename a folder
delete_folder	Delete a folder (protected folders blocked)
get_server_info	Server status and account connectivity

Environment Variables

Variable	Default	Description
MCP_API_KEY	—	Required in production. Bearer token to secure the MCP server
CONFIG_PATH	config.yml	Path to config file
POKE_WEBHOOK_URL	from config	Overrides webhook URL in config
POKE_API_KEY	from config	Overrides Poke API key in config
PORT	3000	HTTP server port

Poke Setup

Connect your MCP server to Poke at poke.com/settings/connections. Add the bearer token (MCP_API_KEY) in the connection auth settings.

The IDLE watcher automatically forwards new emails to Poke. You can also use the tools directly through Poke's AI agent.