Connecting AI Agents to TrekMail via MCP

The TrekMail MCP server lets compatible AI clients manage your email infrastructure through natural language. Its catalog covers domains, mailboxes, White Label branding and teams, Drive, email, calendar, migrations, support, billing, and related services through the same TrekMail API.

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 excluded by a selected toolset, read-only mode, transport limits, or a local safety setting. A narrowly scoped email credential therefore advertises a compact email tool list.

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

• A connection-specific toolset, 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, or 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 on operations that require it, so a retry does not repeat the same operation.
• Two-step delete: mailbox deletion requires explicit intent and confirmation, then moves the mailbox to Recently deleted for recovery.
• Self-hosted safety controls: an administrator running their own stdio MCP server can require approval for delete, send, and migration actions.
• 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. Adding Drive Storage also gives the agent the Drive capabilities the account is entitled to use, including browsing, upload, sharing, restore, and purge.
  • Starter: Full Drive, full Email Verifier, and read-only access across the remaining areas (domains, mailboxes, migrations, tickets, and more). Use the dashboard for write actions that Starter does not expose through the API, such as creating migrations, replying to tickets, or changing auto-reply.
  • Pro / Agency: Full read and write access across every family.
  • White Label trial or add-on: Adds branding, client/team, and activity tools while its entitlement is active. Without it, those schemas are omitted. During cancellation grace, only the owner receives the read tools.
• First time? The Start tour button on the AI Agents & API page walks through connecting an agent, the per-client steps, manual tokens, connected apps, and the audit log.
• For the OAuth paths (1, 2, 3) you do not need to create a token by hand. Your client creates it through the browser authorization flow. For the self-hosted stdio path (4), 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.

Shortcut: the Connect Agent tab of the AI Agents & API page asks which client you use and then shows that client's exact route, the menu path, or the config file and a ready snippet with your address already in it. If your client is listed there, follow that instead of the generic steps below.

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.

Client-specific example: Cursor

Cursor has no screen for a remote server. It reads ~/.cursor/mcp.json (or .cursor/mcp.json inside a project):

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

Client-specific example: Windsurf

Windsurf reads ~/.codeium/windsurf/mcp_config.json. Note the key is serverUrl, not url, a remote server configured with url is ignored:

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

Save the file and restart the client so it picks up the change. The first connection opens your browser to approve access.

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

These controls apply only to the self-hosted stdio MCP process that you run. They do not turn a TrekMail product feature on or off.

Drive tools for agents

With an ops token that includes Drive scopes, the MCP server provides tools for spaces, usage, browsing, uploads, files, folders, Trash, bulk operations, public share links, sync-device password management, and Drive Add-on status. Your connection sees the tools allowed by its scopes.

For a Drive-only agent, set TREKMAIL_API_TOKEN and grant only the scopes the workflow needs. If you run self-hosted stdio, keep destructive actions disabled 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. Local stdio safety controls. When you run the self-hosted stdio server, its administrator can require approval for write, sending, or migration actions. Hosted MCP uses the scopes approved during OAuth instead.
3. TREKMAIL_READ_ONLY=true, which drops every write tool regardless of scopes and flags.

So a self-hosted connection can be deliberately limited even when its token has broader scopes. Hosted MCP remains limited to the permissions approved during OAuth.

Domain tools (ops token)

See Domain Aliases via API and MCP for plan behavior, response states, safe removal, and receive-only routing rules.

White Label tools (ops token)

The white_label toolset contains 20 tools and appears only when the account entitlement, current membership, and credential scopes allow it. Branding is configured per domain; the remaining tools manage setup, clients, team access, and activity. Active White Label is required for writes. During cancellation grace, only the owner keeps the read tools.

An agent can run brand setup end to end: set the brand, copy the returned dns_records, publish them with apply_cloudflare_dns, then verify and check the status. Access-changing calls are capped by the caller's live membership and domain boundary even when the token requested broader scopes. See the White Label Branding API and MCP Guide and Manage White Label Teams with API and MCP.

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 change access. A locally hosted stdio administrator can require TREKMAIL_ALLOW_DESTRUCTIVE=true before they are available; 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 and test tools above change settings or make a connection test. A locally hosted stdio administrator can require TREKMAIL_ALLOW_DESTRUCTIVE=true before they are available; 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

If the mailbox has a Default CC or Default BCC set in Settings → Profile, it is added to what send_message and schedule_message send, exactly as it is to mail written in the web app, an address already on the message is not added twice. Pass apply_default_recipients: false to leave it off a single message. This does not reach mail sent through a desktop or phone mail client over SMTP, which never passes through the API. | report_spam | Report a message as spam, moves to Junk and trains the filter | | report_ham | Mark a Junk message as not spam, moves to Inbox and trains the filter | | bulk_action | Apply an action (read, star, delete, move, spam) to up to 50 messages at once |

Folders

Attachments

Drafts

Both return the draft's uid and uidvalidity. Keep that pair together: update_draft requires the epoch so an old, reused UID can never delete a different message after the Drafts folder is recreated. A draft found with list_messages should first be opened with read_message, which returns its current uidvalidity. An update returns a new pair and the old UID stops working. On a server without UIDPLUS, both values can be null even though a new draft was saved; refresh Drafts and open the draft before updating it.

Both also accept an optional idempotency_key. Leave it out and every call is treated as a new one, so saving the same draft twice gives you two drafts. Pass the same key when you are retrying a call that may already have gone through, and you get the first result back instead of a duplicate.

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 controls for self-hosted stdio

When you run the stdio MCP server yourself, TREKMAIL_ALLOW_DESTRUCTIVE controls whether that local process permits delete and other write actions. Set it to true only if you trust the agent to handle mailbox deletion. This setting does not change feature availability in hosted TrekMail.

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 from a self-hosted process. Set TREKMAIL_ALLOW_SENDING=false when your agent should only read messages. list_scheduled works without this control; it 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 self-hosted environment control because they are safety or 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 in self-hosted stdio: Set TREKMAIL_ALLOW_DESTRUCTIVE=true in that MCP process's environment. This applies to delete and other write actions, including messages, folders, contacts, calendar, identities, templates, blocked senders, and scheduled messages.
• A self-hosted stdio send tool returns "Sending is disabled": Set TREKMAIL_ALLOW_SENDING=true in that MCP process's 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.
• Self-hosted stdio migration write tools return errors: Set TREKMAIL_ALLOW_MIGRATION=true in that MCP process's 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 and appends a replacement, so the draft gets a new UID identity. Use both uid and uidvalidity from the response for anything that follows; the pair you passed in no longer identifies the replacement.
• A copy of every message arrives somewhere you did not put it: the mailbox has a Default CC or Default BCC set in Settings → Profile. It applies to what this mailbox sends, including through the API. Clear it there, or pass apply_default_recipients: false to leave it off one message.
• Calendar event not found: Events are scoped to the specific mailbox. Confirm the message token was issued for the correct mailbox.