Connecting AI Agents to TrekMail via MCP

The TrekMail MCP server lets compatible AI clients manage your email infrastructure through natural language. Its full stdio catalog contains 235 tools across domains, mailboxes, Drive, email, calendar, migrations, support, billing, and related services. Those tools call the same TrekMail API whose current /api/v1 surface contains 244 registered routes.

The full catalog is not loaded into every conversation. TrekMail builds tools/list from the active credential: tools outside its scopes are omitted, as are tools disabled by a selected toolset, read-only mode, transport limits, or a safety gate. A narrowly scoped email credential therefore advertises a compact email tool list instead of all 235 schemas.

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 permissions, and the client gets a token scoped to your account. No long-lived tm_live_ token is copied into the client. Revoke any connection from AI Agents & API → Tokens → Connected apps at any time.

What you get

• Up to 235 agent tools, filtered before registration to the permissions and safety settings of the current connection.
• 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 Start tour button on the AI Agents & API page walks through browser authorization, manual tokens, connected apps, and the audit log.
• 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. Remote MCP client (recommended)

Use this path when your AI client supports remote MCP servers and browser authorization.

1. Open the MCP, integrations, or connectors settings in your client.
2. Choose Add remote MCP server or Add custom connector. The exact label depends on the client.
3. Enter:
   • Name: TrekMail
   • Remote MCP server URL: https://trekmail.net/mcp
4. Confirm the connection. Your browser opens TrekMail's authorization page.
5. Sign in, review the requested permissions, and approve access. Return to the client when the browser confirms the connection.

The first authorization issues a time-limited token. Compatible clients refresh it automatically. To disconnect, use the client's disconnect action or revoke the app from TrekMail's Tokens → Connected apps.

2. CLI or desktop client

For a client that accepts an stdio command, use the client-neutral bridge below:

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

Configure that command as an MCP server in your client. The first connection opens your browser for authorization.

Some clients also provide their own command for adding a remote MCP server. That is equally valid; use https://trekmail.net/mcp as the server URL and follow the client's prompts.

Client-specific example: Claude Code

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

Client-specific example: 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 235 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.

Which of them an agent can actually see is decided by three things, all applied before tools/list answers:

1. Your token's scopes. A tool whose capability your token does not carry is never registered.
2. The safety flags. Read tools are always available. Every tool that creates, changes or deletes something requires TREKMAIL_ALLOW_DESTRUCTIVE=true; the tools that put mail on the wire require TREKMAIL_ALLOW_SENDING; the migration test tools require TREKMAIL_ALLOW_MIGRATION. All three default to off. Some rows below repeat this individually — the absence of such a note does not mean a tool is ungated.
3. TREKMAIL_READ_ONLY=true, which drops every write tool regardless of scopes and flags.

So a full-scope ops token and a message token with no flags set advertise the read tools only; the three flags together bring the list up to the full catalog.

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 members open through their own regular mailbox account in Webmail and, when enabled, delegated native IMAP/SMTP access. It has no direct password login. 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.

After creating, converting, or changing membership, call get_mail_client_setup with a regular member mailbox id. Read shared_mailboxes.items[], wait for native_access_ready=true, and check send_as_ready before configuring sending. The response supplies exact Inbox/Sent/Archive/Junk paths and operation flags; SMTP does not save the shared Sent copy. A retryable native_access_sync_failed from permission removal, permission update, or conversion means the service deliberately kept the previous state.

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 62 tools covering the full webmail surface, including connected external accounts. Tools are organized by feature area.

Hosted OAuth and local stdio identify the mailbox differently. On hosted HTTP MCP, every message-tool schema includes a required mailbox_id; the server uses it to mint a short-lived token for that mailbox. On local stdio MCP, TREKMAIL_MESSAGE_TOKEN is already bound to one mailbox, so those same tools do not accept mailbox_id. A connected inbox is a second level of selection: pass external_account_id in addition to mailbox_id on hosted MCP, or in addition to the bound message token on stdio.

Seven of the 62 message tools manage connected accounts, and five manage From identities and reply policy. Use both families for the Gmail-style workflow where an agent reads a connected Gmail inbox but sends an authorized business address through a domain route or saved SMTP profile. See Send As Addresses via API and MCP.

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.