TrekMail MCP Server

A Model Context Protocol (MCP) server that exposes the TrekMail API v1 as 185 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:

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

Tools (185)

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)

• update_domain_catch_all — Configure or clear the catch-all address

• retry_domain_dkim — Retry DKIM key provisioning

• update_domain_note — Update the admin note on a domain

• bulk_add_domains — Add up to 20 domains in one call

DNS (ops token)

• get_dns_requirements — Get required DNS records for a domain

• dns_recheck — Trigger async DNS verification (returns check ID)

• get_dns_check — 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

• create_mailbox_generated_password — Create mailbox with auto-generated one-time password (optional storage_allocation_mb carves out dedicated storage from the account pool; omit for shared)

• change_mailbox_password — Change the password for a mailbox (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

• update_mailbox_note — 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)

• bulk_create_mailboxes — 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)

• create_invites_bulk — 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)

Forwarding (ops token)

• get_forwarding — Get forwarding config for a mailbox

• set_forwarding — Configure forwarding targets, enable/disable, keep-copy

Mail Filters (ops token)

• list_mail_rules — List all mail filters for a mailbox

• get_mail_rule — Get a single mail filter by ID

• create_mail_rule — Create a new filter with conditions and actions

• update_mail_rule — Update an existing filter

• delete_mail_rule — Delete a filter (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)

• reorder_mail_rules — Change filter execution order

Auto-Reply (ops token)

• get_auto_reply — Get vacation auto-reply settings for a mailbox

• set_auto_reply — Configure auto-reply subject, message, dates, and list skipping

Sieve (ops token)

• get_sieve_script — Get the raw Sieve script for a mailbox

• upload_sieve_script — Upload a raw Sieve script for a mailbox

Delete Intents (ops token, two-step)

• create_delete_intent — Step 1: create a time-limited delete intent

• confirm_delete_intent — Step 2: confirm and execute deletion (irreversible)

Messages (message token)

• list_messages — List messages in a mailbox folder with cursor pagination

• read_message — Get a single message by IMAP UID with full body

• send_message — Send an email from the mailbox (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

• update_message_flags — Update flags (read/unread, starred/unstarred) on a message

• download_attachment — Download a single attachment by index from a message

• download_all_attachments — Download all attachments as a ZIP archive

• get_raw_message — 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)

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

• list_scheduled — List pending scheduled messages

• 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)

• list_contact_groups — List contact groups

• create_contact_group — Create a new contact group

• update_contact_group — Rename or update a contact group

• delete_contact_group — Delete a contact group (requires TREKMAIL_ALLOW_DESTRUCTIVE=true)

• add_contact_group_members — Add contacts to a group

• remove_contact_group_members — Remove contacts from a group

Calendar (message token)

• list_calendar_events — List calendar events with optional date range filter

• create_calendar_event — Create a new calendar event

• update_calendar_event — Update an existing calendar event

• delete_calendar_event — 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

• prepare_reply_all — 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)

• list_blocked_senders — List blocked sender addresses

• block_sender — Block a sender address (moves future mail to Junk)

• unblock_sender — Unblock a sender address

SMTP (ops token)

• get_smtp_config — View current SMTP mode and connection details

• update_smtp_config — Update SMTP configuration (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

• delete_smtp_connection — Delete a custom SMTP connection (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

• test_smtp — Start an async SMTP connection test (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

• get_smtp_test_status — Poll SMTP test results

Tickets (ops token)

• list_tickets — List support tickets with optional status/category filters

• get_ticket — Get ticket details

• get_ticket_messages — Get all messages in a ticket conversation

• create_ticket — Create a new support ticket

• reply_to_ticket — Reply to an existing ticket

• close_ticket — Close a ticket

Account (ops token)

• whoami — Get current token info and permissions

• get_account — Get account details, plan, limits, and usage

• get_billing_status — Get billing and subscription info

• list_invoices — List invoice history

Message Token Management (ops token)

• create_message_token — Create a message API token for a mailbox (returns plaintext once)

• list_message_tokens — List all message tokens for a mailbox

• revoke_message_token — Revoke a message token (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

Migrations (ops token)

• test_migration_connection — Validate IMAP credentials and discover source folders with message counts

• list_migrations — List migrations with optional status/mailbox filters

• get_migration — Get detailed migration status including per-folder progress

• start_migration — Start a new email migration (gated: TREKMAIL_ALLOW_MIGRATION + confirm_start=true)

• cancel_migration — Cancel a running migration (always available — safety operation, requires confirm_cancel=true)

• retry_migration — Retry a failed or cancelled migration (gated: TREKMAIL_ALLOW_MIGRATION + confirm_retry=true)

• delete_migration — Delete a migration record (gated: TREKMAIL_ALLOW_MIGRATION + confirm_delete=true)

Bulk Migrations (ops token)

• preview_bulk_migration — Validate and preview a bulk migration batch (gated: TREKMAIL_ALLOW_MIGRATION)

• start_bulk_migration — Start a bulk migration batch (gated: TREKMAIL_ALLOW_MIGRATION + confirm_start=true)

• list_bulk_migrations — List bulk migration batches with optional status filter

• get_bulk_migration — Get details of a bulk migration batch

• cancel_bulk_migration — Cancel an active bulk batch (requires confirm_cancel=true)

• retry_bulk_migration — Retry failed jobs in a batch (gated: TREKMAIL_ALLOW_MIGRATION + confirm_retry=true)

• resume_bulk_migration — Resume a paused batch (requires confirm_resume=true)

• delete_bulk_migration — Delete a terminal bulk migration batch (gated: TREKMAIL_ALLOW_MIGRATION + confirm_delete=true)

• update_bulk_migration_job_password — Update source password for a failed job (gated: TREKMAIL_ALLOW_MIGRATION)

Spam Metrics (ops token)

• get_spam_metrics — Get daily spam protection metrics for a domain

• get_spam_summary — Get aggregated spam protection summary for a domain

Email Verifier (ops token)

• verify_email — Verify a single email address

• verify_email_bulk — Submit a bulk verification job. Response includes a breakdown { probe, skip, deep_savings } block alongside credits_charged.

• verify_job_status — Check job progress and results

• verify_job_download — Download job results as CSV

• verify_credits — Check remaining credit balance

• verify_list_jobs — List all verification jobs

• verify_cancel_job — Cancel a running job and refund unprocessed credits

• verify_delete_job — Permanently delete a job and all results (GDPR)

Pricing note for Deep mode: addresses on Gmail, Yahoo, Outlook, iCloud, AOL and similar large free email providers are billed at 1 credit each (the Quick rate) even when submitted to verify_email_bulk with mode: "deep". Deep Check adds value through a per-mailbox SMTP probe, but those providers don't allow it — they accept every test and only bounce fake addresses asynchronously. Business domains still cost 2 credits in Deep mode. The breakdown block in the response shows the split (probe = full-Deep addresses, skip = free-provider addresses billed at 1, deep_savings = credits saved vs. flat Deep pricing).

Cloudflare (ops token)

• validate_cloudflare_token — Validate a Cloudflare API token

• list_cloudflare_zones — List DNS zones accessible by a Cloudflare token

• connect_cloudflare_domains — Connect domains to a Cloudflare account (creates new domains if needed)

• preview_cloudflare_dns — Preview DNS changes that would be applied via Cloudflare

• apply_cloudflare_dns — Apply DNS changes to Cloudflare-managed zones

• list_cloudflare_tokens — List stored Cloudflare tokens

• delete_cloudflare_token — Delete a stored Cloudflare token (gated: TREKMAIL_ALLOW_DESTRUCTIVE)

Idempotency

All mutating tools (POST/PUT) generate deterministic idempotency keys from sha256(tool_name + canonical_params). This means:

• The same tool call with the same params always produces the same key

• Agent retries hit the API's idempotency cache — no duplicate side effects

• You can override with an explicit idempotency_key parameter on any mutating tool

Safety

Two-Step Delete

Mailbox deletion requires two separate tool calls:

1. create_delete_intent → returns intent with 10-minute expiry

2. confirm_delete_intent → executes deletion (irreversible)

Destructive Operations Gate

Both delete tools require TREKMAIL_ALLOW_DESTRUCTIVE=true. Without it, they return an error message explaining how to enable.

The confirm_delete_intent tool has an additional confirm: true parameter that must be explicitly set.

Sending Safety Gates

The send_message tool has two independent safety gates that must both pass:

1. Environment gate: TREKMAIL_ALLOW_SENDING=true must be set in the environment

2. Per-call gate: confirm_send=true must be passed as a parameter

This dual-gate design prevents accidental email sends. The agent must both be configured to allow sending and explicitly confirm each send.

Migration Safety Gates

The start_migration, retry_migration, and delete_migration tools require TREKMAIL_ALLOW_MIGRATION=true in the environment. cancel_migration is always available as a safety operation. test_migration_connection requires the gate because it makes outbound IMAP connections. Read-only tools (list_migrations, get_migration) work without any gate.

Additionally, each write tool requires a per-call confirmation parameter (confirm_start, confirm_cancel, or confirm_retry set to true).

Claude Desktop Configuration

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["/path/to/trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "true"
      }
    }
  }
}

Claude Code Configuration

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["/path/to/trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "true"
      }
    }
  }
}

Workflow Examples

DNS Recheck Loop

1. dns_recheck(domain_id: 5) → { check_id: 42 }
2. get_dns_check(check_id: 42) → { status: "pending" }
3. (wait) get_dns_check(check_id: 42) → { status: "complete", results: {...} }

Create Mailbox + Forwarding

1. create_mailbox_generated_password(domain_id: 5, local_part: "alice")
   → { id: 10, email: "alice@example.com", password: "..." }
2. set_forwarding(mailbox_id: 10, enabled: true, targets: ["alice@gmail.com"], keep_copy: true)

Create Mailbox with Dedicated Storage

# Carve out 5 GB just for this mailbox — other shared mailboxes can't grow into it.
1. create_mailbox_generated_password(
     domain_id: 5,
     local_part: "ceo",
     storage_allocation_mb: 5120
   ) → { id: 11, email: "ceo@example.com", password: "...", is_pooled_storage: false, storage_allocation_mb: 5120 }

Bulk Create with Mixed Storage Modes

# Mix shared and dedicated in one call. The sum of all storage_allocation_mb
# across the batch is checked against the available pool — if it would
# over-commit, the entire batch is rejected with 422 storage_pool_exceeded.
1. bulk_create_mailboxes(items: [
     { domain_id: 5, local_part: "support" },                                  # shared
     { domain_id: 5, local_part: "founder",  storage_allocation_mb: 10240 },  # 10 GB dedicated
     { domain_id: 5, local_part: "team-lead", storage_allocation_mb: 5120 },  # 5 GB dedicated
   ])

Invite Flow

1. create_invite(domain_id: 5, local_part: "bob", recipient_email: "bob@gmail.com")
   → { id: 1, status: "pending", invite_url: "..." }

Invite with Pre-Allocated Storage

# Pending dedicated invites count against the available pool until they
# are redeemed or expire — no over-committing.
1. create_invite(
     domain_id: 5,
     local_part: "exec",
     recipient_email: "exec@external.com",
     storage_allocation_mb: 10240
   ) → { id: 2, status: "pending", storage_allocation_mb: 10240 }
# When the recipient redeems, the new mailbox inherits the 10 GB dedicated allocation.
# If the pool no longer fits at redeem time, the new mailbox falls back to shared
# (the recipient sees a notice on the success page) — redeem itself never fails.

Safe Delete

1. create_delete_intent(mailbox_id: 10) → { id: 7, expires_at: "...", status: "pending" }
2. confirm_delete_intent(intent_id: 7, confirm: true) → { status: "confirmed" }

Monitor Inbox

1. list_messages(folder: "INBOX", limit: 10, unread_only: true)
   → { messages: [...], pagination: { has_more: true, next_before_uid: 45 } }
2. read_message(uid: 50) → { from, subject, body_text, body_html, attachments: [...] }

Email Migration

1. test_migration_connection(source_host: "imap.gmail.com", source_port: 993, source_security: "ssl", source_email: "user@gmail.com", source_password: "app-password")
   → { success: true, folders: { "INBOX": 1234, "Sent": 567, ... } }
2. start_migration(mailbox_id: 10, provider: "gmail", source_host: "imap.gmail.com", source_port: 993, source_security: "ssl", source_email: "user@gmail.com", source_password: "app-password", target_password: "mailbox-pass", confirm_start: true)
   → { id: 5, status: "pending", ... }
3. get_migration(id: 5) → { status: "processing", progress: 45, folders: [...] }
4. (poll) get_migration(id: 5) → { status: "completed", progress: 100, imported_messages: 1801 }

Send Email with Confirmation

1. send_message(
     to: ["alice@example.com"],
     subject: "Weekly Report",
     body_text: "Please find the report attached.",
     confirm_send: true,
     idempotency_key: "weekly-report-2026-02-07"
   ) → { status: "queued", message_id: "uuid@trekmail.net", queued_at: "..." }

Drive Tools

42 tools for the /api/v1/drive/* REST surface (38 file/folder/share/addon tools + 4 sync-device password tools added 2026-05-23). Drive is available through both the TrekMail REST API and this MCP server when the ops token has the matching Drive scopes. See the TrekMail app/API docs for the full REST reference.

{space} parameters accept "account" (account-drive singleton), "mailbox:N" (mailbox-personal), or a numeric DriveSpace.id.

Plan / addon gating

Drive scopes light up for any account on a paid plan OR with an active Drive Storage Add-on (mirrors how verify:* works for the Email Verifier). Free + addon active is a fully supported path — mint a token with drive:account:read etc. and it works. When the addon enters its 7-day post-cancellation grace window, write/share/ purge tokens lose access; read tokens keep working.

Drive API/MCP scopes:

Upload flow

Default — drive_file_upload (one tool, all three steps):

drive_file_upload(space="account", local_path="/path/to/report.pdf",
                  folder_id=42, client_mime="application/pdf")

The wrapper:

1. Reads file size and calls drive_upload_initiate.

2. Streams the file straight to the returned upload URL(s). Bytes do NOT pass through MCP infrastructure beyond the wrapper process — and they never touch the API server. Memory stays bounded for files of any size (tested with multi-GB).

3. For files ≥ 100 MB, uses multipart: 50 MB chunks, captures each upload part ETag, refreshes any expired part URL once before failing.

4. Calls drive_upload_complete to register the file as available.

5. On any error along the way, calls drive_upload_abort to release the quota reservation. (The reservation is also reclaimed by the server-side cleanup — abort is a fast path, not a guarantee.)

Low-level primitives (drive_upload_initiate etc.) stay available for agents that want to drive the PUT phase themselves — e.g. uploads from a remote source instead of the MCP host's filesystem.

Audit attribution

Every mutating Drive tool stamps actor_type='api_token' and api_token_id=<token id> on the audit row, so the dashboard's API audit tab can filter by token. The mailbox/user context the token is acting on behalf of is preserved in the existing mailbox_id / metadata.actor_user_id fields.

Development

# Install dependencies
npm install

# Run in dev mode (tsx, no build required)
TREKMAIL_BASE_URL=https://trekmail.net TREKMAIL_API_TOKEN=tm_live_test npm run dev

# Build
npm run build

# Run tests
npm test

# Watch tests
npm run test:watch

# Type-check only
npm run lint