Skip to content

junxit/mcp-forwardemail

BranchesTags

Repository files navigation

ForwardEmail MCP Server

⚠️ UNOFFICIAL - This is an unofficial MCP server for ForwardEmail. It is not affiliated with, endorsed by, or supported by Forward Email LLC.

An MCP (Model Context Protocol) server that provides comprehensive access to the ForwardEmail API for Claude Desktop, Cline, and other MCP-compatible clients.

Features

  • 71 MCP tools covering the ForwardEmail API
  • Domain Management - List, create, update, delete domains; verify DNS/SMTP records; allowlist/denylist; S3 connection test
  • Alias Management - Full CRUD for email aliases with forwarding rules
  • Outbound Email - Send emails via API, check limits, manage queue
  • Sieve Filtering - Manage server-side Sieve filtering scripts
  • Mailbox (alias credentials) - Contacts (CardDAV), Calendars & events (CalDAV), Messages & Folders (IMAP)
  • Team Collaboration - Invite members, manage roles
  • Security - Password generation for IMAP/SMTP access, TXT record encryption
  • Async/Await - Built with modern Python async patterns
  • Type Safety - Full type hints with Pydantic models

Prerequisites

Installation

Using uvx (Recommended)

uvx --from git+https://github.com/junxit/mcp-forwardemail.git forwardemail-mcp

Using pip

pip install git+https://github.com/junxit/mcp-forwardemail.git

From Source

git clone https://github.com/junxit/mcp-forwardemail.git
cd mcp-forwardemail
uv pip install -e .

Configuration

Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "forwardemail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/junxit/mcp-forwardemail.git", "forwardemail-mcp"],
      "env": {
        "FORWARDEMAIL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Local Development with Claude Desktop

{
  "mcpServers": {
    "forwardemail": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-forwardemail", "run", "forwardemail-mcp"],
      "env": {
        "FORWARDEMAIL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cline / Continue Extension

Add to your MCP settings:

{
  "forwardemail": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/junxit/mcp-forwardemail.git", "forwardemail-mcp"],
    "env": {
      "FORWARDEMAIL_API_KEY": "your_api_key_here"
    }
  }
}

Environment Variable

Alternatively, set the API key as an environment variable:

export FORWARDEMAIL_API_KEY="your_api_key_here"

Alias Credentials (for mailbox tools)

Most tools authenticate with your account API key. The mailbox tools — Contacts, Calendars, Calendar Events, Messages, Folders, and Sieve Scripts (the alias-auth variant) — instead use a specific alias's own credentials, so each of those tools takes two extra arguments:

  • alias_username — the full alias email (e.g. me@example.com)
  • alias_password — a password generated for that alias via alias_generate_password

These are passed per tool call (no extra environment variables), so you can work with any alias across any domain in the same session. Generate a password first:

"Generate an IMAP/CardDAV password for the alias me@example.com, then list its folders."

Available Tools

Account (3 tools)

Tool Description
account_get Retrieve account information
account_create Create a new account
account_update Update account details

Domains (13 tools)

Tool Description
domains_list List all domains
domain_create Create a new domain
domain_get Get domain details
domain_update Update domain settings
domain_delete Delete a domain
domain_verify_records Verify DNS records
domain_verify_smtp Verify SMTP records (DKIM, DMARC)
domain_catchall_passwords_list List catch-all passwords
domain_catchall_password_create Create catch-all password
domain_catchall_password_delete Delete catch-all password
domain_allowlist_update Replace the domain sender allowlist
domain_denylist_update Replace the domain sender denylist
domain_test_s3_connection Test custom S3 storage connection

Aliases (6 tools)

Tool Description
aliases_list List domain aliases
alias_create Create a new alias
alias_get Get alias details
alias_update Update an alias
alias_delete Delete an alias
alias_generate_password Generate IMAP/SMTP password

Outbound Emails (5 tools)

Tool Description
emails_limit_get Get daily sending limit
emails_list List outbound emails
email_create Send an email
email_get Get email details
email_delete Cancel/delete an email

Invites (3 tools)

Tool Description
invite_accept Accept a domain invite (requires the invite token)
invite_create Invite a user to domain
invite_delete Remove an invite

Members (2 tools)

Tool Description
member_update Update member role
member_delete Remove a member

Logs (1 tool)

Tool Description
logs_download Request log download (emailed as CSV)

Encrypt (1 tool)

Tool Description
encrypt_txt_record Encrypt TXT record value

Sieve Filters — domain (6 tools, API key)

Tool Description
domain_sieve_list List an alias's Sieve scripts
domain_sieve_create Create a Sieve script
domain_sieve_get Get a Sieve script
domain_sieve_update Update a Sieve script
domain_sieve_delete Delete a Sieve script
domain_sieve_activate Activate a Sieve script

The tool groups below use alias credentials (alias_username + alias_password) — see Alias Credentials.

Contacts — CardDAV (5 tools)

Tool Description
contacts_list List contacts
contact_create Create a contact
contact_get Get a contact
contact_update Update a contact
contact_delete Delete a contact

Calendars — CalDAV (5 tools)

Tool Description
calendars_list List calendars
calendar_create Create a calendar
calendar_get Get a calendar
calendar_update Update a calendar
calendar_delete Delete a calendar

Calendar Events — CalDAV (5 tools)

Tool Description
calendar_events_list List calendar events
calendar_event_create Create an event (iCalendar)
calendar_event_get Get an event
calendar_event_update Update an event
calendar_event_delete Delete an event

Messages — IMAP (5 tools)

Tool Description
messages_list List and search messages
message_create Create/append a message
message_get Get a message
message_update Update flags/labels/folder
message_delete Delete a message

Folders — IMAP (5 tools)

Tool Description
folders_list List folders
folder_create Create a folder
folder_get Get a folder
folder_update Rename a folder
folder_delete Delete a folder

Sieve Scripts — alias auth (6 tools)

Tool Description
sieve_scripts_list List Sieve scripts
sieve_script_create Create a Sieve script
sieve_script_get Get a Sieve script
sieve_script_update Update a Sieve script
sieve_script_delete Delete a Sieve script
sieve_script_activate Activate a Sieve script

Usage Examples

List Your Domains

Ask Claude: "List my ForwardEmail domains"

Create an Email Alias

Ask Claude: "Create an alias called 'support' on example.com that forwards to admin@gmail.com"

Send an Email

Ask Claude: "Send an email from hello@example.com to user@gmail.com with subject 'Test' and body 'Hello!'"

Verify Domain Setup

Ask Claude: "Verify the DNS records for example.com"

API Coverage Notes

The ForwardEmail Contacts (CardDAV), Calendars/Events (CalDAV), Messages and Folders (IMAP), and alias Sieve scripts authenticate with alias credentials (alias email + generated password) rather than the account API key. These are now fully supported — see Alias Credentials for how to supply them.

Not currently wrapped:

  • Push tokens (/v1/push-tokens) — registering a device push token requires a real device/browser to mint the token value, so it is out of scope for this server.
  • Internal/billing endpoints (Stripe, PayPal, WebSocket, etc.).

Troubleshooting

"Authentication failed" error

  • Verify your API key is correct
  • Check that the key is properly set in env section of your MCP config
  • Ensure there are no extra spaces or quotes around the key

"FORWARDEMAIL_API_KEY environment variable is required"

  • Make sure you've added the env section to your MCP configuration
  • Restart Claude Desktop after changing the configuration

Tool not found

  • Restart Claude Desktop to reload MCP servers
  • Check Claude Desktop logs for startup errors

Development

# Clone the repository
git clone https://github.com/junxit/mcp-forwardemail.git
cd mcp-forwardemail

# Install in development mode
uv pip install -e ".[dev]"

# Run tests (--extra dev pulls pytest/respx)
uv run --extra dev pytest -v

# Run the server locally
FORWARDEMAIL_API_KEY="your_key" uv run forwardemail-mcp

How to Test

# Run unit tests
uv run --extra dev pytest -v

# Run single test file
uv run --extra dev pytest tests/test_endpoints.py -v

How to Uninstall

# If installed via pip/uv
pip uninstall forwardemail-mcp

# Remove from Claude Desktop config
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# and remove the "forwardemail" entry from mcpServers

Cleanup Local Files

# Remove Python cache files
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -type f -name "*.pyc" -delete
find . -type f -name "*.pyo" -delete

# Remove virtual environments
rm -rf .venv venv ENV .uv

# Remove build artifacts
rm -rf build dist *.egg-info .eggs

# Remove test/coverage artifacts
rm -rf .pytest_cache .coverage htmlcov .tox

# Remove the project directory (if installed from source)
cd .. && rm -rf mcp-forwardemail

Assumptions

  • ForwardEmail API remains stable at https://api.forwardemail.net
  • API authentication continues to use HTTP Basic Auth
  • MCP SDK version 1.0+ maintains current interface
  • Users have valid ForwardEmail accounts with API access enabled

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Links

License

MIT License - see LICENSE file.

Disclaimer: This is an unofficial, community-maintained project. ForwardEmail is a trademark of Forward Email LLC. This project is not affiliated with, endorsed by, or supported by Forward Email LLC.

About

⚠️ **UNOFFICIAL** - This is an unofficial MCP server for [ForwardEmail](https://forwardemail.net). It is not affiliated with, endorsed by, or supported by Forward Email LLC.

Topics

python email mcp claude anthropic llm-tools model-context-protocol mcp-server forwardemail

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages