Connecting AI Agents (MCP)

The TrekMail MCP server lets AI agents manage your email infrastructure through natural language. It exposes 181 tools covering domains, DNS, spam metrics, mailboxes, invites, forwarding, mail filters, auto-reply, sieve, safe deletion, SMTP configuration, Cloudflare DNS integration, Drive file storage, 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.

What you get

• 181 agent tools covering domains, DNS, spam metrics, mailboxes, invites, forwarding, sieve, safe deletion, SMTP configuration, Cloudflare DNS integration, support tickets, account and billing, email migrations, email verification (8 verifier tools), 38 Drive tools for file storage, and the full webmail API surface (52 message tools).
• Dual-token architecture — separate ops token (infrastructure) and message token (full webmail operations).
• 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

• Create an API token on the AI Agents & API → Tokens page.
• For email read/send, create a message token via the API using your ops token (see the Connect Agent tab for instructions).
• All plans can connect agents. Nano plans can use Email Verifier tools only. Starter plans add read-only infrastructure tools plus verifier; Starter plans also have mailbox forwarding available via the dashboard (not via API write tools). Pro and Agency plans get full access (read + write).
• Have Node.js 18+ installed (for local setup), or Docker for container-based setup.
• 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.

Install the MCP server

Clone the repository and build:

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

Claude Desktop

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

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

Environment variables

Drive tools for agents

With an ops token that includes Drive scopes, the MCP server exposes 38 Drive tools for spaces, usage, browsing, uploads, files, folders, Trash, bulk operations, public share links, and read-only Drive Add-on status. The complete MCP server now exposes 181 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)

DNS tools (ops token)

Mailbox tools (ops token)

Sieve tools (ops token)

Delete tools (ops token)

Migration tools (ops token)

Ticket tools (ops token)

SMTP tools (ops token)

Spam metrics tools (ops token)

Account tools (ops token)

Message token management (ops token)

Message tools (message token)

The message token unlocks 52 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. Upgrade to Pro for full API write access.
• 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.