TrekMail MCP Server

A Model Context Protocol (MCP) server that exposes the TrekMail API v1 as 284 agent tools. This is a thin adapter — all business logic lives in the TrekMail API; this server handles transport, authentication, retries, and safety gates.

Current release: package 1.17.0, catalogue 2026-10-14.3.

Connect in Claude

For the hosted service, open TrekMail in the Claude directory, select Connect, sign in to TrekMail and approve the requested permissions. TrekMail is published as a Community connector. Available tools depend on the connected account's plan and permissions.

For a White Label dashboard, add a custom connector using the MCP URL shown in that dashboard and your own brand name. The shared TrekMail listing signs in on TrekMail and does not replace your branded connection.

See the connection guide for other clients. The npm and Docker instructions below run the MCP adapter locally; the adapter still calls your configured TrekMail API.

Quickstart

npm

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 \
npm start

Docker

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 \
  trekmail-mcp

Dual-Token Architecture

The MCP server supports two independent token types. At least one is required:

Token	Env Var	Prefix	Unlocks
Ops token	TREKMAIL_API_TOKEN	tm_live_	220 infrastructure tools (White Label branding, clients, team access, client storage limits and activity; domains; DNS; mailboxes; Drive; migrations; SMTP; tickets; account; billing; verifier; Cloudflare; and related administration)
Message token	TREKMAIL_MESSAGE_TOKEN	tm_msg_	64 message tools (messages, attachments, drafts, bulk actions, folders, scheduled send, contacts, contact groups, calendar, compose helpers, connected accounts, identities, templates, blocked senders)

Tools are registered conditionally — only token types you provide get their tools. You can supply one or both:

# Infrastructure only
TREKMAIL_API_TOKEN=tm_live_your_token npm start

# Messages only
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token npm start

# Both
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
npm start

Environment Variables

Variable	Required	Default	Description
TREKMAIL_BASE_URL	Yes	—	Your TrekMail instance URL
TREKMAIL_API_TOKEN	At least one token	—	Ops token (must start with tm_live_)
TREKMAIL_MESSAGE_TOKEN	At least one token	—	Message token (must start with tm_msg_)
TREKMAIL_TIMEOUT_MS	No	30000	Request timeout in milliseconds
TREKMAIL_USER_AGENT	No	trekmail-mcp/1.17.0	User-Agent header
TREKMAIL_ALLOW_DESTRUCTIVE	No	false	Enable high-impact changes (White Label access/branding, mailbox storage sizes and client storage limits, delete intents, domain deletion, forwarding, password changes, SMTP, credential revocation, Drive trash/purge, and message deletion)
TREKMAIL_ALLOW_SENDING	No	false	Enable external sends, including send_message and White Label invitations
TREKMAIL_ALLOW_MIGRATION	No	false	Enable migration write tools (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection)
TREKMAIL_TOOLSETS	No	all	Comma-separated product sets to register, for example email or email,contacts,calendar
TREKMAIL_SCOPE_AWARE_REGISTRATION	No	true	Discover the token's effective capabilities and domain/mailbox constraints at startup and omit unusable tool schemas; set false only as a compatibility escape hatch
TREKMAIL_READ_ONLY	No	false	Register read tools only, even when the token can write

Tool visibility is the intersection of token capability, TREKMAIL_TOOLSETS, TREKMAIL_READ_ONLY, and transport support. A token limited to some domains also does not get update_account, set_client_limit or remove_client_limit, which the API refuses to it whatever its scopes; update_account and drive_folder_stop_sharing are withheld from a token limited to some mailboxes (no mailbox stops a folder share, as in webmail). Runtime API authorization remains authoritative. Account Drive and Mailbox Drive deliberately share one drive toolset; all White Label capabilities share white_label. The concrete resource, membership, entitlement, and token constraints decide what a call can access: a token limited to some mailboxes, for one, reaches Account Drive only through the folders shared with all mailboxes, as those mailboxes do in webmail. Shared mailbox member tools require the matching shared mailbox permission from your dashboard role as well as the mailbox API permission. Roles with Read access can list members; changing members requires permission to manage shared mailboxes. Compact email, contacts, calendar, and email-settings selections also include the existing read-only list_mailboxes tool so an agent can discover the required mailbox ID without loading the full administration toolset.

For a normal mailbox project, this is the compact configuration:

TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_TOOLSETS=email \
TREKMAIL_SCOPE_AWARE_REGISTRATION=true \
npm start

This is the beginning of the README. Read the rest at the original. Read the full README ↗