Connecting AI Agents to TrekMail via MCP

The TrekMail MCP server lets AI agents manage your email infrastructure through natural language. It exposes 216 tools covering domains, DNS, spam metrics, mailboxes, shared (team) mailboxes, invites, forwarding, mail filters, auto-reply, sieve, safe deletion, SMTP configuration, per-domain White Label branding, Cloudflare DNS integration, Drive file storage, Drive sync-device password management, support tickets, account and billing, email migrations, email verification, and the full webmail feature surface — messages, folders, attachments, drafts, scheduled send, contacts, contact groups, calendar, compose helpers, identities, templates, and blocked senders.

Pick how you want to connect

Paths 1–3 use OAuth 2.1: the first time you connect, your browser opens TrekMail's consent page, you review the requested scopes, and Claude gets a token scoped to your account. No long-lived tm_live_ tokens involved. Revoke any connection from AI Agents & API → Tokens → Active OAuth Connections at any time.

What you get

• 216 agent tools covering domains, DNS, spam metrics, outbound deliverability rollups and per-recipient hard/soft bounces with SMTP status codes (new), mailboxes (with storage quota detail), shared (team) mailboxes — list/add/update/remove members plus create-and-convert lifecycle (new), invites, forwarding, sieve, safe deletion, SMTP configuration, per-domain White Label branding — set brand identity, logos, branded hosts, and verify DNS (new), Cloudflare DNS integration, support tickets, account and billing, email migrations, email verification (8 verifier tools), 42 Drive tools for file storage and sync-device password management, and the full webmail API surface (53 message tools).
• OAuth 2.1 + dynamic client registration — your AI client registers itself, walks you through a browser consent page, and gets a scoped token. No copy-paste of long-lived tokens for the web/desktop/CLI paths.
• Dual-token architecture — separate ops token (infrastructure) and message token (full webmail operations). When you connect via OAuth, message tokens are minted automatically per mailbox as needed.
• Automatic idempotency — retries never create duplicate resources.
• Two-step delete — mailbox deletion requires explicit intent + confirmation.
• Destructive operations gate — delete tools are disabled by default.
• Sending safety gates — email sending requires both an environment gate and per-call confirmation.
• Migration safety gates — migration write tools are disabled by default and require per-call confirmation.
• Full audit logging — every API and MCP operation is logged with 90-day retention.

Before you start

• All plans can connect agents.
  • Nano — Email Verifier tools. Pick up a Drive Storage Add-on and your agent also gets the full Drive tool set (browse, upload, share, restore, purge — 42 tools).
  • Starter — Full Drive, full Email Verifier, and read-only across the rest (domains, mailboxes, migrations, tickets, and so on). For writes the Starter API doesn't expose — creating migrations, replying to tickets, changing auto-reply — use the dashboard.
  • Pro / Agency — Full read + write across every family.
• First time? The Guide button on the AI Agents & API page walks you through connection methods, token setup, and the audit log step by step.
• For the OAuth paths (1, 2, 3) you don't need to create any token by hand — your client does it through the browser. For the self-hosted stdio path (4) you do create a tm_live_ token in the dashboard first.

1. Claude.ai (recommended)

The fastest way — works entirely in your browser, no software to install.

1. Open claude.ai/customize/connectors.
2. Click the + in the Connectors header → Add custom connector.
3. Fill in the dialog:
   • Name: TrekMail
   • Remote MCP server URL: https://trekmail.net/mcp
4. Click Add. Claude opens a popup to https://trekmail.net/oauth/authorize — log in to your TrekMail account if you aren't already, review the requested scopes, click Authorize.
5. The popup closes and the connector appears under Connected. You can now ask Claude things like "list my TrekMail domains" or "create a mailbox alice@…" in any chat.

The first authorization issues a token good for 30 days. Refreshes happen silently as long as Claude.ai is the active client. To disconnect, click the connector → Disconnect in claude.ai, or revoke from TrekMail's Tokens → Active OAuth Connections.

2. Claude Desktop / Claude Code

Same OAuth flow, configured in your local Claude config file. The desktop app handles the browser popup just like claude.ai does.

Claude Code (CLI)

claude mcp add trekmail https://trekmail.net/mcp -t http

The first time you run a Claude Code session after this, your browser opens for the consent step.

Claude Desktop

Edit your config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp",
      "transport": "http"
    }
  }
}

Restart Claude Desktop. The first time you mention TrekMail in a chat, the OAuth popup opens.

3. mcp-remote (CLI)

Useful for testing or for non-Anthropic MCP clients that don't yet support remote OAuth servers directly — mcp-remote is a small Node bridge from stdio to remote HTTP.

npx -y mcp-remote https://trekmail.net/mcp

The first run opens your browser for OAuth. After that the token is cached under ~/.mcp-auth/ and used automatically.

You can wire this into any stdio MCP client by pointing it at the mcp-remote command instead of a local Node entry point.

4. Self-hosted stdio (Claude Desktop / Docker / npm)

If you want static tm_live_ tokens instead of OAuth (e.g. for unattended servers, private TrekMail instances, or container deploys), clone and run the stdio MCP package on your own host.

Create an API token on the AI Agents & API → Tokens page first. For email read/send, also create a message token via the API using your ops token (see the Connect Agent tab for instructions).

Install the MCP server

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

Claude Desktop (stdio)

Add this to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./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": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Update the args path to point to where you cloned the repository. Replace the tokens with your own. You can omit TREKMAIL_MESSAGE_TOKEN if you only need infrastructure tools, or omit TREKMAIL_API_TOKEN if you only need message tools. At least one token is required.

Claude Code (stdio)

Add this to your Claude Code MCP settings (.claude/settings.json or project-level config):

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./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": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

If you prefer Docker, build the image from the repo and run it:

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 \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

Local npm (development)

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 \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

Stdio environment variables

Drive tools for agents

With an ops token that includes Drive scopes, the MCP server exposes 42 Drive tools for spaces, usage, browsing, uploads, files, folders, Trash, bulk operations, public share links, sync-device password management (rclone / Cyberduck / X-Plore / DAVx⁵ credentials), and read-only Drive Add-on status. The complete MCP server now exposes 216 tools.

For a Drive-only agent, set TREKMAIL_API_TOKEN and grant only the scopes the workflow needs. Keep TREKMAIL_ALLOW_DESTRUCTIVE=false unless the agent is running a reviewed purge or empty-trash job. Drive Add-on purchase, resize, and cancel are not MCP tools; agents can read add-on status and pricing, but billing changes stay in the dashboard.

See Drive MCP Tools Overview and Connecting AI Agents to TrekMail Drive.

Available tools

The MCP server exposes these tools to connected agents. Tools are registered conditionally based on which tokens are provided.

Domain tools (ops token)

White Label branding tools (ops token)

Branding is configured per domain — a domain runs its own brand (custom), inherits the account default (inherit), or is off. Settings always save; the branded dashboard.yourbrand.com / mail.yourbrand.com hosts only go live once the White Label add-on is active (without it they stay draft).

get_domain_branding is read-only and always available; the other six are disabled unless TREKMAIL_ALLOW_DESTRUCTIVE=true. An agent can run the whole setup autonomously — set the brand, read the dns_records, write them with apply_cloudflare_dns, then verify_domain_branding_dns and poll. See the White Label Branding API and MCP Guide.

DNS tools (ops token)

Mailbox tools (ops token)

Shared mailbox tools (ops token)

A shared mailbox is a team inbox (support@, sales@) that other mailboxes open from their own webmail. Access is flat — everyone can read, and can_send is the only toggle (reply-capable vs read-only). There are no member roles.

Shared mailbox lifecycle (ops token)

The three lifecycle tools and the three member-write tools (add/update/remove) are disabled unless TREKMAIL_ALLOW_DESTRUCTIVE=true; list_shared_mailbox_members is read-only and always available.

Sieve tools (ops token)

Delete tools (ops token)

Migration tools (ops token)

Ticket tools (ops token)

SMTP / domain-routing tools (ops token)

SMTP is configured per domain — each domain points at managed platform sending or at a saved SMTP profile (your own provider, reusable across domains), and a single account-wide default decides what new domains start on.

The write/test tools above are disabled unless TREKMAIL_ALLOW_DESTRUCTIVE=true; get_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_test_status, and get_account_smtp_default are read-only and always available.

Legacy SMTP tools (deprecated)

These account-level tools remain for backward compatibility but no longer control per-domain routing — use the domain-routing tools above instead.

Spam metrics tools (ops token)

Account tools (ops token)

Message token management (ops token)

Message tools (message token)

The message token unlocks 53 tools covering the full webmail surface. Tools are organized by feature area.

Core messages

Folders

Attachments

Drafts

Scheduled send

Contacts

Contact groups

Calendar

Compose helpers

These tools prepare the data for a reply or forward — they do not send anything. Pass the returned data directly to send_message or save_draft.

Identities (send-from addresses)

Templates

Blocked senders

Email Verifier tools (ops token)

Email Verifier tools are available on all plans, including Nano. The only limitation is your credit balance.

Cloudflare tools (ops token)

Cloudflare tools are available on Pro and Agency plans.

Safety and destructive operations

By default, TREKMAIL_ALLOW_DESTRUCTIVE is false. With this setting, delete tools return an error explaining how to enable them. Set it to true only if you trust the agent to handle mailbox deletion.

Even with destructive operations enabled, deletion always requires two steps and the agent must explicitly set confirm: true. See Safety Rails and Delete Intents for details.

Sending safety gates

The send_message and schedule_message tools have two independent safety gates that must both pass:

1. Environment gate: TREKMAIL_ALLOW_SENDING=true must be set when starting the MCP server.
2. Per-call gate: The agent must pass confirm_send=true as a parameter on every call.

This dual-gate design prevents accidental email sends. Set TREKMAIL_ALLOW_SENDING=false (the default) if your agent should only read messages. Note that list_scheduled works without any gate — the sending gate applies only to creating or sending scheduled messages.

Migration safety gates

Migration write tools (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection, preview_bulk_migration, start_bulk_migration, retry_bulk_migration) have two independent safety gates:

1. Environment gate: TREKMAIL_ALLOW_MIGRATION=true must be set when starting the MCP server.
2. Per-call gate: Each tool requires its own confirmation parameter (confirm_start=true, confirm_retry=true, or confirm_delete=true).

cancel_migration, cancel_bulk_migration, and resume_bulk_migration are always available regardless of the environment gate — they are safety/resumption operations. They still require per-call confirmation parameters.

Read-only migration tools (list_migrations, get_migration, list_bulk_migrations, get_bulk_migration) work without any gates.

Quick fixes

• Agent cannot connect: Verify the build/index.js path is correct and you ran npm run build after cloning.
• "Missing bearer token" errors: Check that at least one of TREKMAIL_API_TOKEN or TREKMAIL_MESSAGE_TOKEN is set.
• Read-only tools work but writes fail: Your token is on a Starter plan. Drive writes work on Starter (full Drive surface). For other writes — provisioning mailboxes, starting migrations, replying to tickets — upgrade to Pro, or use the dashboard.
• Delete tools return errors: Set TREKMAIL_ALLOW_DESTRUCTIVE=true in the environment. This applies to all delete/destructive tools — messages, folders, contacts, calendar, identities, templates, blocked senders, and scheduled messages.
• Send tool returns "Sending is disabled": Set TREKMAIL_ALLOW_SENDING=true in the environment.
• Send tool returns "Send not confirmed": The agent must pass confirm_send=true on each send_message or schedule_message call.
• No message tools appear: Ensure TREKMAIL_MESSAGE_TOKEN is set with a valid tm_msg_ token.
• Migration write tools return errors: Set TREKMAIL_ALLOW_MIGRATION=true in the environment.
• 503 on migration start: The server is at migration capacity. Retry in a few minutes.
• Attachment download fails: Attachments are returned as base64. Large attachments (up to 25 MB) may take a few seconds. download_all_attachments returns a base64-encoded ZIP of all attachments.
• Draft disappeared after update: update_draft deletes the old draft UID and creates a new one. Always use the returned new UID for subsequent operations.
• Calendar event not found: Events are scoped to the specific mailbox. Confirm the message token was issued for the correct mailbox.