Trekmail Mcp Server

TrekMail MCP Server

A Model Context Protocol (MCP) server that exposes the TrekMail API v1 as 228 agent tools. This is a thin adapter — all business logic lives in the TrekMail API; this server handles transport, authentication, retries, and safety gates.

Quickstart

npm

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
npm start

Docker

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  trekmail-mcp

Dual-Token Architecture

The MCP server supports two independent token types. At least one is required:

| Token | Env Var | Prefix | Unlocks | |-------|---------|--------|---------| | Ops token | TREKMAIL_API_TOKEN | tm_live_ | 167 infrastructure tools (domains, DNS, mailboxes, mail-client setup, invites, aliases, shared mailbox members, forwarding, mail filters, auto-reply, sieve, delete intents, migrations, SMTP, tickets, account, billing, spam stats, verifier, message token management, Cloudflare DNS, Drive, and Drive sync-device passwords) | | Message token | TREKMAIL_MESSAGE_TOKEN | tm_msg_ | 61 message tools (messages, attachments, drafts, bulk actions, folders, scheduled send, contacts, contact groups, calendar, compose helpers, connected accounts, identities, templates, blocked senders) |

Tools are registered conditionally — only token types you provide get their tools. You can supply one or both:

# Infrastructure only
TREKMAIL_API_TOKEN=tm_live_your_token npm start

# Messages only
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token npm start

# Both
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
npm start

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TREKMAIL_BASE_URL | Yes | — | Your TrekMail instance URL | | TREKMAIL_API_TOKEN | At least one token | — | Ops token (must start with tm_live_) | | TREKMAIL_MESSAGE_TOKEN | At least one token | — | Message token (must start with tm_msg_) | | TREKMAIL_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds | | TREKMAIL_USER_AGENT | No | trekmail-mcp/1.7.0 | User-Agent header | | TREKMAIL_ALLOW_DESTRUCTIVE | No | false | Enable destructive tools (delete intents, domain delete, password change, pause, SMTP config, revoke token, delete Cloudflare token, Drive trash/purge/empty-trash, Drive sync-device revoke/rotate, message deletes) | | TREKMAIL_ALLOW_SENDING | No | false | Enable send_message tool | | TREKMAIL_ALLOW_MIGRATION | No | false | Enable migration write tools (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection) |

Tools (228)

> The full catalog is 228 tools over stdio. On the hosted HTTP transport > drive_file_upload is intentionally not registered (its local_path would read > files on our server — see the note in src/tools/drive.ts), so the HTTP MCP > exposes 227. Tools also split by token type: 61 need a message token > (tm_msg_), the rest an ops token (tm_live_).

Domains (ops token)

• list_domains — List domains with optional status/search filters
• get_domain — Get details for a specific domain
• create_domain — Add a new domain to the account
• delete_domain — Delete a domain (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• updatedomaincatch_all — Configure or clear the catch-all address
• retrydomaindkim — Retry DKIM key provisioning
• updatedomainnote — Update the admin note on a domain
• getdomainsignature — Read per-domain email signature settings (mode, position, HTML)
• updatedomainsignature — Set per-domain signature (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• bulkadddomains — Add up to 20 domains in one call

DNS (ops token)

• getdnsrequirements — Get required DNS records for a domain
• dns_recheck — Trigger async DNS verification (returns check ID)
• getdnscheck — Poll DNS check status/results

Mailboxes (ops token)

• list_mailboxes — List mailboxes with optional domain/search filters
• get_mailbox — Get details for a specific mailbox
• getmailclient_setup — Get password-free IMAP/SMTP settings, actual sending readiness, and localized guides for five app families
• getapplemail_profile — Generate a password-free Apple Mail .mobileconfig file as Base64 (13 locales)
• createmailboxgenerated_password — Create mailbox with auto-generated one-time password (optional storage_allocation_mb carves out dedicated storage from the account pool; omit for shared)
• changemailboxpassword — Change the password for a mailbox (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• updatemailboxnote — Update the admin note on a mailbox
• pause_mailbox — Disable a mailbox (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• resume_mailbox — Re-enable a paused mailbox
• enable_imap — Enable IMAP access for a mailbox (required for Message API)
• bulkcreatemailboxes — Create 1-100 mailboxes at once with per-item storage_allocation_mb (sum across the batch is validated against the available pool)

Invites (ops token)

• create_invite — Send a setup invite to a recipient (optional storage_allocation_mb pre-allocates dedicated storage; the recipient inherits it at redeem)
• createinvitesbulk — Send up to 100 setup invites in one call (per-item storage_allocation_mb supported)

Aliases (ops token)

• list_aliases — List all aliases for a mailbox (includes primary address and plan limits)
• create_alias — Add an alias to a mailbox (cross-domain supported, Starter+ plans)
• update_alias — Toggle receiving, sending, or active/inactive status
• delete_alias — Permanently remove an alias (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

Shared Mailbox Members (ops token)

• listsharedmailbox_members — List the members of a shared (team) mailbox, with each member's role and read/send/manage permissions
• addsharedmailbox_member — Add an existing user mailbox to a shared mailbox, optionally as manager (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• updatesharedmailbox_member — Change a member's role or toggle their send-as permission (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• removesharedmailbox_member — Remove a member from a shared mailbox; the last member cannot be removed (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

Forwarding (ops token)

• get_forwarding — Read the current forwarding config for a mailbox. Returns the targets array (one or more destinations), keep_copy, and destination_limit (the plan-tier cap so the agent can preflight an set_forwarding call without trial-and-error).
• set_forwarding — Configure one or more forwarding destinations for a mailbox, plus enable/disable and keep-copy. The targets array accepts up to 30 entries client-side; the server enforces the actual per-plan cap — Starter 5, Pro 15, Agency 30 — and returns a 422 limit_exceeded error with the cap if you pass more. CRLF / loop / self-forward / MX validation is run per destination, so a single bad entry rejects the whole save.

Mail Filters (ops token)

• listmailrules — List all mail filters for a mailbox
• getmailrule — Get a single mail filter by ID
• createmailrule — Create a new filter with conditions and actions
• updatemailrule — Update an existing filter
• deletemailrule — Delete a filter (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• reordermailrules — Change filter execution order

Auto-Reply (ops token)

• getautoreply — Get vacation auto-reply settings for a mailbox
• setautoreply — Configure auto-reply subject, message, dates, and list skipping

Sieve (ops token)

• getsievescript — Get the raw Sieve script for a mailbox
• uploadsievescript — Upload a raw Sieve script for a mailbox

Delete Intents (ops token, two-step)

• createdeleteintent — Step 1: create a time-limited delete intent
• confirmdeleteintent — Step 2: confirm and execute deletion (irreversible)

Messages (message token)

> Many message tools accept an optional external_account_id to operate on a > connected external mailbox (Gmail/Outlook/IMAP) instead of the primary mailbox. > The id is always scoped to the token's mailbox (cross-mailbox access is > impossible); discover valid ids with list_external_accounts. Supported on: > list_messages, read_message, send_message, move_message, > update_message_flags, delete_message, list_folders, download_attachment, > download_all_attachments, get_raw_message, save_draft, update_draft, and > bulk_action (native actions only: read/unread/star/unstar/delete/move). > report_spam/report_ham (and bulk_action spam/notspam) train THIS server's > spam filter, which doesn't apply to a remote provider, so they reject > external_account_id — move to the provider's Junk folder instead.

• list_messages — List messages in a mailbox folder with cursor pagination (optional external_account_id)
• read_message — Get a single message by IMAP UID with full body (optional external_account_id)
• send_message — Send an email from the mailbox — or, with external_account_id, from a connected account via its own SMTP (dual safety gates, validates total recipients ≤ 10, requires body)
• delete_message — Permanently delete a message by IMAP UID (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• move_message — Move a message to a different IMAP folder
• list_folders — List all IMAP folders for the mailbox
• updatemessageflags — Update flags (read/unread, starred/unstarred) on a message
• download_attachment — Download a single attachment by index from a message
• downloadallattachments — Download all attachments as a ZIP archive
• getrawmessage — Get the full RFC 822 raw source of a message
• save_draft — Save a new draft via IMAP APPEND
• update_draft — Update an existing draft (replaces the old draft)
• report_spam — Report a message as spam (trains Rspamd Bayesian filter)
• report_ham — Mark a message as not spam (trains Rspamd Bayesian filter)
• bulk_action — Perform a bulk action on up to 50 messages (read, unread, star, unstar, delete, move, spam, notspam)

Connected accounts (message token)

Connect and manage external mailboxes (Gmail/Outlook/IMAP) the mailbox reads and sends through. Credentials are never returned by any tool.

• listexternalaccounts — List connected external accounts (id, email, provider, status) — the source of valid external_account_id values
• detectexternalaccount — Detect provider preset (host/port/encryption, app-password vs OAuth) from an email address
• testexternalaccount — Test unsaved IMAP/SMTP credentials without persisting (requires TREKMAIL_ALLOW_MIGRATION=true)
• createexternalaccount — Connect an external account (test-gated; requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• updateexternalaccount — Update a connected account's settings/credentials (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• testsavedexternal_account — Re-test a saved account and lift its circuit breaker (requires TREKMAIL_ALLOW_MIGRATION=true)
• deleteexternalaccount — Remove a connected account and its stored credentials (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)

Folders (message token)

• create_folder — Create a new IMAP folder
• rename_folder — Rename an existing IMAP folder
• delete_folder — Delete an IMAP folder and its contents (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• empty_folder — Empty all messages from a folder without deleting the folder

Scheduled Messages (message token)

• schedule_message — Schedule a message to be sent at a future time (optional IANA timezone resolves naïve datetimes; explicit ISO offset always wins)
• list_scheduled — List pending scheduled messages
• reschedule_message — Re-time a pending scheduled message in place (no resend, lighter throttle than schedule + cancel)
• cancel_scheduled — Cancel a scheduled message before it sends

Contacts (message token)

• list_contacts — List contacts with optional search
• create_contact — Create a new contact
• update_contact — Update a contact's details
• delete_contact — Delete a contact (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• import_contacts — Import contacts from CSV or VCF data
• export_contacts — Export all contacts as VCF

Contact Groups (message token)

• listcontactgroups — List contact groups
• listcontactgroup_members — List the contacts in a group (paginated)
• createcontactgroup — Create a new contact group
• updatecontactgroup — Rename or update a contact group
• deletecontactgroup — Delete a contact group (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)
• addcontactgroup_members — Add contacts to a group
• removecontactgroup_members — Remove contacts from a group

Calendar (message token)

• listcalendarevents — List calendar events with optional date range filter
• createcalendarevent — Create a new calendar event
• updatecalendarevent — Update an existing calendar event
• deletecalendarevent — Delete a calendar event (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)

Compose Helpers (message token)

• prepare_reply — Get pre-filled reply data (quoted body, headers) for a message
• preparereplyall — Get pre-filled reply-all data for a message
• prepare_forward — Get pre-filled forward data for a message

Identities (message token)

• list_identities — List send-from identities for the mailbox
• create_identity — Create a new send-from identity
• update_identity — Update an identity's display name, signature, or default flag
• delete_identity — Delete a send-from identity (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)

Templates (message token)

• list_templates — List message templates
• create_template — Create a new message template
• update_template — Update a message template
• delete_template — Delete a message template (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)

Blocked Senders (message token)

• listblockedsenders — List blocked sender addresses
• block_sender — Block a sender address (moves future mail to Junk)
• unblock_sender — Unblock a sender address

SMTP (ops token)

• getsmtpconfig — View current SMTP mode and connection details
• updatesmtpconfig — Update SMTP configuration (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• deletesmtpconnection — Delete a custom SMTP connection (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• test_smtp — Start an async SMTP connection test (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• getsmtptest_status — Poll SMTP test results

> The five tools above are the legacy account-level SMTP controls — deprecated for routing (kept for back-compat only). Use the per-domain SMTP routing + account-default tools below for outbound delivery configuration.

Domain SMTP Routing (ops token)

• getdomainsmtp — Get a domain's outbound route (mode + selected profile; effective_smtp_mode resolves inherit to the account default)
• setdomainsmtp — Set a domain's route: platform (managed) / profile (saved profile) / not_configured / inherit (follow the account default) (gated: TREKMAIL_ALLOW_DESTRUCTIVE)
• listdomainsmtp_profiles — List the account's reusable saved SMTP profiles plus per-profile usage counts
• createdomainsmtp_profile — Create a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trekmail
• Source: trekmail/mcp-server
• License: MIT
• Homepage: https://trekmail.net/

Install and usage instructions live in the source repository linked above.