Connecting AI Agents to TrekMail via MCP

Choose and edit app permissions

During OAuth approval, choose Read only or select individual permissions. Sending and changing/deleting messages are separate. Message reading includes contacts, calendars, templates and blocked senders; the required account and mailbox lookup permissions are included automatically. Use your branded dashboard’s MCP address for a White Label connection.

Open API key details or a connected app and choose Edit access, review the changes, then confirm. An API key keeps its secret. Reduced scopes, resource access and expiry also restrict existing mailbox tokens and cancel sends that have not begun. New OAuth connections can be narrowed immediately; adding access requires a new approval. Editing an older connection disconnects it and saves the choices for reconnection. Mailbox message tokens can only lose permissions or have their expiry shortened.

Connect from the Claude directory

TrekMail is published as a Community connector in the Claude directory.

Open TrekMail in Claude, select Connect, sign in to TrekMail and approve the permissions you need. No API token or custom server URL is needed.

If your Claude workspace restricts connectors, ask its administrator to enable TrekMail. You can revoke access in TrekMail under AI Agents & API, Tokens, Connected apps.

Your own White Label brand: use the MCP address shown in your branded dashboard and name the connector after your brand. Add it as a custom connector; the public TrekMail listing signs in on TrekMail and does not replace your branded connection.

Available actions: your plan, membership and approved permissions apply to every connection. The reference below covers the general API and self-hosted MCP too. In directory connections, password and credential setup opens an authenticated dashboard page through a get_*_setup_link tool; do not send secrets in chat. Creating or replacing a mail app password in the ChatGPT/OpenAI and Claude directory profiles returns a secure dashboard link instead of the secret. Purchases and subscription changes stay in the dashboard.

ChatGPT: until public directory installation is available, use the custom connection described in the official quickstart. Enable Developer mode, add your dashboard's MCP URL in Plugins, authenticate, then install the personal plugin and use it in a Work chat. Public installation instructions will be added after publication.

First request and troubleshooting

• Show my domains.
• Show the files in my Drive.

If Claude blocks the connector, ask your workspace administrator to enable it. Cancelled sign-in or revoked access? Open the connection steps again to reconnect.

Other connection methods

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. A credential confined to some domains also does not get update_account, set_client_limit or remove_client_limit, and one confined to some mailboxes does not get update_account or drive_folder_stop_sharing: the API would refuse them anyway.

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": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://trekmail.net/mcp"]
    }
  }
}

Restart Claude Desktop. When the local bridge starts, follow its browser authorization prompt.

Client-specific example: Cursor

Configure Cursor with a JSON file:

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

Client-specific example: Windsurf

For Cascade, open …, Open MCP config file and add this entry. This is the Cascade configuration; other agents can use a different file.

{
  "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 four 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.
4. The connection's domain or mailbox confinement. A token or connector limited to some domains never gets update_account, set_client_limit or remove_client_limit, and one limited to some mailboxes never gets update_account or drive_folder_stop_sharing. The API refuses these tools to such a connection anyway.

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 23 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, client storage limits, 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. Client storage limits can be changed only by a connection that reaches every domain of the account; see Give Each Client Their Own Storage Limit. 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)

New mailboxes created by agents, including bulk creation and invites, follow Account settings > New mailboxes > Mail apps need app passwords, on by default. Changing this setting does not switch existing mailboxes. App passwords are for mail apps; Message API tokens still work independently. For scopes, password handoff and mode changes, see Mail App Passwords via API and MCP.

Shared mailbox tools (ops token)

A shared mailbox is a team inbox (support@, sales@) with no direct sign-in or shared password. Read (can_read) opens its inbox and, when available, its shared IMAP folders. Send as (can_send) allows sending as its address. Each member has their own permissions; there are no member roles. When send-only access is enabled, can_read=false with can_send=true lets someone send from their own webmail or mail app without reading the team inbox. The Message API cannot send from this address with send-only access.

Permission changes can return 422 no_access_left when both permissions would be off, 422 send_only_disabled when the requested Read change is unavailable, or 422 last_reader when the last active reader would lose access. Use Remove to end all access, and give another active member Read before removing the last reader. Each of these errors also returns shared_mailbox_id, member_id for an existing member, and a hint naming the request that fixes it.

Shared mailbox lifecycle (ops token)

Converting back removes every member. Set a new webmail password, then create app passwords for mail apps on the Security tab.

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. shared_mailboxes.items[] lists shared folders for people with Read. Wait for native_access_ready=true and check send_as_ready before configuring full read-and-send access. SMTP does not save a Sent copy; the app chooses its Sent folder. delegated_send_addresses is a separate list of available team From addresses, not shared folders or a promise that sending is ready. Sign in with the member’s own address and an app password, using the hosts returned by setup, including on White Label. A retryable native_access_sync_failed means the previous state was kept.

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 64 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 64 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

send_message returns once the message is accepted, before it is actually sent, so confirm it went out with get_message_delivery; a sending_limit_exceeded error says which allowance was reached and when it renews (resets_at), and the agent should not retry before then. get_message_delivery works with any message token for the same mailbox, not only the one that sent the message, so the short-lived tokens of hosted MCP, or a renewed token, can still check earlier sends; an unknown request_id returns 404.

In get_mailbox_sending_limits, remaining_today is how many more recipients this mailbox can reach today. When the lowest allowance is the account-wide total, limit_today is null, and so is remaining_today until that total is spent (then it is 0). An ops token reads the account total with get_sending_limits.

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.

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)

The Message API and message tools send from a shared inbox only with both Read and Send as, using shared_mailbox_id and the member’s token. list_identities returns only addresses supported by that API. Team-address entries provided in personal webmail are not listed or accepted as API identities and cannot be changed or deleted through these tools.

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.
• Send tool returns sending_limit_exceeded: A sending allowance is used up. The error says which one (dimension) and when it renews (resets_at); do not retry before then. If the limit is the number of recipients in one message, split the message instead. get_mailbox_sending_limits shows how many more recipients the mailbox can reach today; its remaining_today is null while the lowest allowance is the account-wide total and some of it is left, and an ops token reads that total with get_sending_limits. TrekMail Sending Limits by Plan explains each limit. A message send_message already accepted can still be refused when it leaves the queue; get_message_delivery then shows it as failed with the same details. A failed send can be sent again later with the same content: the API no longer replays the earlier accepted response for it. A retry of a send that is still pending or was delivered still gets the original response.
• 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.