fortimail-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fortimail-mcp-server Check engine health and show deferred queue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FortiMail MCP Server
Secure AI Gateway for FortiMail — open-source MCP server that speaks only to the FortiMail Engine HTTP API (/v1, Bearer API keys). It does not connect directly to a FortiMail appliance or store appliance admin passwords.
License: MIT. Security disclosures: SECURITY.md.
Features
40+ tools mapped to the FortiMail Engine OpenAPI (
pnpm run codegenregenerates TypeScript types)Bearer-only upstream auth —
fme_...API keys with engine-side scopes (fortimail:read/fortimail:write, etc.)Dual-backend caching — in-memory (default) or Redis, with per-resource TTLs (MCP response cache only)
Retry with exponential backoff — transient HTTP errors
TLS — verify by default; set
FORTIMAIL_VERIFY_CERT=falseonly when appropriateDual transport — Streamable HTTP (remote) or stdio (local)
Input validation — Zod schemas on every tool
Truncation safety — ~25K character cap on tool output (final gate for LLM context)
Optional HTTP authentication — Bearer token and/or API key for
POST /mcp
Related MCP server: FortiManager MCP Server
Architecture (thin client)
Layer | Role |
This repo | Auditable MCP "driver": maps tools → Engine REST paths, adds caching and truncation |
FortiMail Engine (proprietary) | Policy, FortiMail quirks, rate limits, optional multi-tenant routing |
FortiMail appliance | Reached only by the engine, not by this MCP process |
Upstream contract: vendored openapi/openapi.json. When the engine API changes, refresh that file and run pnpm run codegen.
What the AI can do for you
Workflow | Example prompt | Tools involved |
Engine health | "Check FortiMail Engine status with detailed readiness" |
|
Queue triage | "List the incoming queue, then show full headers for mkey …" |
|
Redirect stuck mail | "Search the deferred queue for recipient X, reroute to backup.example.com" |
|
Log investigation | "List elog files, download the segment …" |
|
Reporting | "List reports, trigger mail stats for task Daily_Stats" |
|
Security model
Mode | Notes |
stdio | MCP runs on the operator machine. |
HTTP | Protect |
Threat model: Anyone who can call /mcp with valid HTTP auth can do whatever the engine API key allows. Protect Redis if used. See SECURITY.md.
Quick Start
pnpm install
pnpm run build
pnpm testRequired environment:
FORTIMAIL_ENGINE_URL=https://your-engine.example.com/v1
FORTIMAIL_ENGINE_API_KEY=fme_your_keyExample .env.local:
FORTIMAIL_ENGINE_URL=https://engine.example.com/v1
FORTIMAIL_ENGINE_API_KEY=fme_...
# FORTIMAIL_VERIFY_CERT=false # only if engine uses a private CA / self-signed certRun:
pnpm start
# HTTP + MCP auth
TRANSPORT=http PORT=3000 MCP_HTTP_BEARER_TOKEN=secret pnpm startEnvironment variables
Variable | Required | Default | Description |
| Yes | — | Engine base URL including |
| Yes | — | Bearer token ( |
| No | verify | Set |
| No |
|
|
| No |
| Redis URL |
| No |
|
|
| No |
| HTTP port |
| No |
| Bind address for HTTP |
| No | — | If set, |
| No | — | If set, |
Authentication tools
fortimail.engine.status— liveness (GET /health); optional detailed readiness (GET /health/detailed, Bearer). Both are requested at the engine origin (same host/port asFORTIMAIL_ENGINE_URLwith/v1stripped), not under/v1.fortimail.auth.logout— no-op (legacy name; engine uses API keys only).fortimail.cache.flush— clears MCP response cache (not the engine server cache).
Publishing to MCP directories (e.g. Smithery)
This server matches Smithery’s URL publishing expectations:
Requirement | How this repo satisfies it |
Streamable HTTP |
|
Auth | If you set |
401 for missing auth | Unauthenticated |
Config schema |
|
If Smithery or another gateway shows “couldn’t authenticate with the upstream server”: the gateway is calling your URL without a valid MCP secret. Set MCP_HTTP_BEARER_TOKEN on the host to match the value users enter in Smithery (or Cursor / ChatGPT connector) for MCP Bearer Token. Optional fields in the JSON Schema do not remove the need for that token when the server enforces HTTP auth.
Cloudflare / WAF: allow SmitheryBot and skip JS challenges on POST /mcp so scans succeed (Smithery troubleshooting). For MCP, also disable caching and response buffering on /mcp so SSE streams are not broken.
Reverse proxy (Traefik / nginx / Dokploy): The upstream must receive the same credential headers the client sends. If Authorization is stripped, configure the proxy to forward it, or have the gateway send X-MCP-Bearer-Token (supported by this server). Some setups copy the client Authorization into X-Forwarded-Authorization — that is supported when the primary Authorization header is missing.
Still failing: Set MCP_HTTP_DEBUG_AUTH=true on the container and retry from ChatGPT; check logs for hasAuthorization / hasXMcpBearerToken / queryKeys (no secrets logged). If all are false, the gateway is not forwarding credentials to your origin.
Name:
fortimail-mcp-serverDescription: MCP client for FortiMail Engine API — domains, users, profiles, queue, reports, logs, SMTP
Required env (process):
FORTIMAIL_ENGINE_URL,FORTIMAIL_ENGINE_API_KEYTransports:
stdio, Streamable HTTP (POST /mcpstreams SSE;GET /mcpreturns 401 without auth, else 405 with hint)
HTTP mode for Cursor / ChatGPT / Claude (remote URL)
Point the client at https://your-host/mcp and configure the same secret the server expects:
Authorization:
Bearer <MCP_HTTP_BEARER_TOKEN>, orHeader:
X-MCP-Bearer-Token: <MCP_HTTP_BEARER_TOKEN>(matches Smitherymcp_bearer_token/x-mcp-bearer-token), orQuery:
?mcp_bearer_token=<token>(less ideal; may appear in logs)
MSP and multi-instance
One process = one engine base URL + one API key. For many tenants or appliances, run multiple MCP instances (or let the engine multiplex tenants — the MCP only forwards the Bearer token). See docs/MULTI_INSTANCE.md.
Licensing and commercial roadmap
Open core: MIT (LICENSE).
Engine: The FortiMail Engine service that implements
openapi.jsonmay be proprietary; this repo stays a thin OSS client.
Contributions: CONTRIBUTING.md. Security: SECURITY.md.
Tool inventory
Engine & cache (3 tools)
fortimail.engine.status/fortimail.auth.logout/fortimail.cache.flush
Domains (7 tools)
fortimail.domains.list/fortimail.domains.get/fortimail.domains.create/fortimail.domains.update/fortimail.domains.deletefortimail.domains.info.get/fortimail.domains.info.update
Users (10 tools)
Mail users:
fortimail.users.list/.get/.create/.update/.deleteUser maps:
fortimail.users.maps.list/.get/.create/.update/.delete
Profiles (20 tools)
GeoIP, Notification, IMAP auth, SMTP auth — CRUD each (e.g.
fortimail.profiles.geoip.list)
Mail queue (6 tools)
fortimail.queue.list/.search/.view/.delete/.reroute/.download
Reports (6), Logs (2), SMTP (2)
fortimail.reports.*,fortimail.logs.*,fortimail.smtp.config.*
Repository layout
src/
├── index.ts
├── constants.ts
├── text-utils.ts
├── generated/engine-schema.ts # pnpm run codegen
├── engine/unwrap.ts
├── services/api-client.ts # EngineClient (Bearer)
└── tools/MCP client configuration (stdio)
{
"mcpServers": {
"fortimail": {
"command": "node",
"args": ["/path/to/fortimail-mcp-server/dist/index.js"],
"env": {
"FORTIMAIL_ENGINE_URL": "https://engine.example.com/v1",
"FORTIMAIL_ENGINE_API_KEY": "fme_..."
}
}
}
}HTTP mode
TRANSPORT=http PORT=3000 MCP_HTTP_BEARER_TOKEN=your-secret node dist/index.jsDevelopment
See CONTRIBUTING.md. Run pnpm test before submitting changes. After updating openapi/openapi.json, run pnpm run codegen.
Available Tools
56 toolsfortimail.auth.logoutFortiMail Logout (no-op)ARead-onlyIdempotent
Purpose: Legacy tool name. Engine mode uses Bearer tokens only — there is no server-side MCP session to end. Returns: Short confirmation. Side effects: None.
Inputs: no named parameters.
fortimail.cache.flushFlush MCP Response CacheAIdempotent
Purpose: Clear the MCP process response cache (in-memory or Redis), not the FortiMail Engine server cache. When to use: When reads look stale after changes made elsewhere. Returns: Confirmation. Side effects: Next reads refetch from the engine.
Inputs: no named parameters.
fortimail.domains.createCreate DomainA
Purpose: Create a domain via the engine (POST /v1/domains/{key}).
Inputs: domain — name; settings — must include ip per engine schema; optional port, status, comment.
Returns: API response body.
Side effects: Creates domain; flushes MCP cache.
Inputs: domain (required), settings.
fortimail.domains.deleteDelete DomainADestructive
Purpose: Delete a domain (DELETE /v1/domains/{key}).
Inputs: domain.
Side effects: Destructive; flushes MCP cache.
Inputs: domain (required).
fortimail.domains.getGet Domain SettingsBRead-onlyIdempotent
Purpose: Load configuration for one domain.
Inputs: domain — domain name (mkey).
Returns: JSON.
Side effects: None (read-only).
Inputs: domain (required).
fortimail.domains.info.getGet Domain InfoCRead-onlyIdempotent
Purpose: Customer/account metadata (GET /v1/domain-info/{key}).
Inputs: domain.
Returns: JSON.
Side effects: None (read-only).
Inputs: domain (required).
fortimail.domains.info.updateUpdate Domain InfoAIdempotent
Purpose: Update metadata (PUT /v1/domain-info/{key}).
Inputs: domain; info — customer_name, customer_email, account_limit, comment.
Side effects: Flushes MCP cache.
Inputs: info (required), domain (required).
fortimail.domains.listList DomainsARead-onlyIdempotent
Purpose: Enumerate mail domains via the FortiMail Engine. When to use: Onboarding, audits, or before editing a domain. Inputs: None. Returns: Markdown list; truncated if very large. Side effects: None (read-only).
Inputs: no named parameters.
fortimail.domains.updateUpdate Domain SettingsBIdempotent
Purpose: Partial update (PUT /v1/domains/{key}).
Inputs: domain; settings — fields to update.
Returns: API response body.
Side effects: Updates domain; flushes MCP cache.
Inputs: domain (required), settings (required).
fortimail.engine.statusFortiMail Engine StatusARead-onlyIdempotent
Purpose: Check connectivity to the FortiMail Engine (liveness and optional detailed readiness).
When to use: After configuring env vars, or when other tools fail with network/auth errors.
Inputs: detailed — if true, call /health/detailed (requires API key with sufficient scope).
Returns: JSON from the engine health endpoints.
Side effects: None.
Inputs: detailed.
fortimail.logs.downloadDownload Log FileCRead-onlyIdempotent
Purpose: POST /v1/logs/download. Response bytes are interpreted as UTF-8 text (use compressed: false for plain text in MCP).
Inputs: log_file (required), compressed.
fortimail.logs.listList Log FilesCRead-onlyIdempotent
Purpose: GET /v1/logs?type=&limit=&offset=.
Inputs: log_type (required), page_size, start_index.
fortimail.profiles.geoip.createCreate GeoIP ProfileC
Purpose: Create GeoIP Profile (see engine OpenAPI for required body fields).
Inputs: key (required), settings.
fortimail.profiles.geoip.deleteDelete GeoIP ProfileCDestructive
Purpose: Delete GeoIP Profile.
Inputs: key (required).
fortimail.profiles.geoip.getGet GeoIP ProfileCRead-onlyIdempotent
Purpose: Get one GeoIP Profile.
Inputs: key (required).
fortimail.profiles.geoip.listList GeoIP ProfilesBRead-onlyIdempotent
Purpose: List GeoIP Profile profiles via the engine. Side effects: None (read-only).
Inputs: no named parameters.
fortimail.profiles.geoip.updateUpdate GeoIP ProfileCIdempotent
Purpose: Update GeoIP Profile.
Inputs: key (required), settings (required).
fortimail.profiles.imap_auth.createCreate IMAP Auth ProfileC
Purpose: Create IMAP Auth Profile (see engine OpenAPI for required body fields).
Inputs: key (required), domain (required), settings.
fortimail.profiles.imap_auth.deleteDelete IMAP Auth ProfileCDestructive
Purpose: Delete IMAP Auth Profile.
Inputs: key (required), domain (required).
fortimail.profiles.imap_auth.getGet IMAP Auth ProfileCRead-onlyIdempotent
Purpose: Get one IMAP Auth Profile.
Inputs: key (required), domain (required).
fortimail.profiles.imap_auth.listList IMAP Auth ProfilesCRead-onlyIdempotent
Purpose: List IMAP Auth Profile profiles via the engine. Side effects: None (read-only).
Inputs: domain (required).
fortimail.profiles.imap_auth.updateUpdate IMAP Auth ProfileCIdempotent
Purpose: Update IMAP Auth Profile.
Inputs: key (required), domain (required), settings (required).
fortimail.profiles.notification.createCreate Notification ProfileC
Purpose: Create Notification Profile (see engine OpenAPI for required body fields).
Inputs: key (required), domain (required), settings.
fortimail.profiles.notification.deleteDelete Notification ProfileCDestructive
Purpose: Delete Notification Profile.
Inputs: key (required), domain (required).
fortimail.profiles.notification.getGet Notification ProfileBRead-onlyIdempotent
Purpose: Get one Notification Profile.
Inputs: key (required), domain (required).
fortimail.profiles.notification.listList Notification ProfilesCRead-onlyIdempotent
Purpose: List Notification Profile profiles via the engine. Side effects: None (read-only).
Inputs: domain (required).
fortimail.profiles.notification.updateUpdate Notification ProfileCIdempotent
Purpose: Update Notification Profile.
Inputs: key (required), domain (required), settings (required).
fortimail.profiles.smtp_auth.createCreate SMTP Auth ProfileC
Purpose: Create SMTP Auth Profile (see engine OpenAPI for required body fields).
Inputs: key (required), domain (required), settings.
fortimail.profiles.smtp_auth.deleteDelete SMTP Auth ProfileCDestructive
Purpose: Delete SMTP Auth Profile.
Inputs: key (required), domain (required).
fortimail.profiles.smtp_auth.getGet SMTP Auth ProfileCRead-onlyIdempotent
Purpose: Get one SMTP Auth Profile.
Inputs: key (required), domain (required).
fortimail.profiles.smtp_auth.listList SMTP Auth ProfilesCRead-onlyIdempotent
Purpose: List SMTP Auth Profile profiles via the engine. Side effects: None (read-only).
Inputs: domain (required).
fortimail.profiles.smtp_auth.updateUpdate SMTP Auth ProfileDIdempotent
Purpose: Update SMTP Auth Profile.
Inputs: key (required), domain (required), settings (required).
fortimail.queue.deleteDelete Queued MailBDestructive
Purpose: DELETE /v1/queue with confirmation header (see engine docs).
Side effects: Destructive.
Inputs: mail_keys (required), queue_type (required).
fortimail.queue.downloadDownload Queued MailDRead-onlyIdempotent
Purpose: Not exposed on the FortiMail Engine OpenAPI in this MCP version. Returns: Error guidance.
Inputs: mail_keys (required), queue_type (required).
fortimail.queue.listList Mail QueueCRead-onlyIdempotent
Purpose: GET /v1/queue with type, offset, limit.
Side effects: None (read-only).
Inputs: queue_type (required), page_size, start_index.
fortimail.queue.rerouteSend Queued Mail to Alternate HostD
Purpose: POST /v1/queue/reroute.
Inputs: mail_keys (required), queue_type (required), alternate_host (required).
fortimail.queue.searchSearch Mail QueueBRead-onlyIdempotent
Purpose: GET /v1/queue with optional sender, recipient, clientIp, sessionId, reason, type.
Side effects: None (read-only).
Inputs: queue_type (required), reason, sender, relation, +5 more.
fortimail.queue.viewView Queued MailCRead-onlyIdempotent
Purpose: GET /v1/queue/view.
Inputs: mail_key (required), account_type (required), open_method.
fortimail.reports.deleteDelete ReportsCDestructive
Purpose: DELETE /v1/reports with query params.
Inputs: report_keys (required), domain, report_class.
fortimail.reports.downloadDownload ReportCRead-onlyIdempotent
Purpose: POST /v1/reports/download (binary payload decoded as UTF-8 text when possible).
Inputs: report_key (required), report_class (required), domain.
fortimail.reports.generate.domain_mail_statsGenerate Domain Mail Statistics ReportD
Purpose: POST /v1/reports/domain-stats.
Inputs: no named parameters.
fortimail.reports.generate.mailbox_statsGenerate Mailbox Statistics ReportC
Purpose: POST /v1/reports/mailbox.
Inputs: task_name (required).
fortimail.reports.generate.mail_statsGenerate Mail Statistics ReportC
Purpose: POST /v1/reports/mail-stats.
Inputs: task_name (required).
fortimail.reports.listList ReportsCRead-onlyIdempotent
Purpose: GET /v1/reports.
Inputs: domain, page_size, start_index, report_class.
fortimail.smtp.config.getGet SMTP ConfigurationCRead-onlyIdempotent
Purpose: GET /v1/smtp-config.
Inputs: no named parameters.
fortimail.smtp.config.updateUpdate SMTP ConfigurationDIdempotent
Purpose: PUT /v1/smtp-config.
Inputs: settings (required).
fortimail.users.createCreate Mail UserA
Purpose: Create mailbox user (POST /v1/domains/{domain}/users/{key}).
Inputs: domain; key; optional settings — password, status, type, displayname (see engine OpenAPI).
Side effects: Flushes MCP cache.
Inputs: key (required), domain (required), settings.
fortimail.users.deleteDelete Mail UserADestructive
Purpose: DELETE /v1/domains/{domain}/users/{key}.
Side effects: Flushes MCP cache.
Inputs: key (required), domain (required).
fortimail.users.getGet Mail UserBRead-onlyIdempotent
Purpose: Fetch one user (GET /v1/domains/{domain}/users/{key}).
Inputs: domain; key — user mkey.
Side effects: None (read-only).
Inputs: key (required), domain (required).
fortimail.users.listList Mail UsersARead-onlyIdempotent
Purpose: List mailbox users for a domain (GET /v1/domains/{domain}/users).
Inputs: domain.
Returns: Markdown summary.
Side effects: None (read-only).
Inputs: domain (required).
fortimail.users.maps.createCreate User MapB
Purpose: POST /v1/user-maps/{key}. Body must include type per engine schema; pass map_type or full body.
Side effects: Flushes MCP cache.
Inputs: key (required), extra, map_type, external_name.
fortimail.users.maps.deleteDelete User MapADestructive
Purpose: DELETE /v1/user-maps/{key}.
Side effects: Flushes MCP cache.
Inputs: key (required).
fortimail.users.maps.getGet User MapARead-onlyIdempotent
Purpose: Find one map by listing /v1/user-maps (no single-GET in OpenAPI).
Inputs: key — internal mkey.
Side effects: None (read-only).
Inputs: key (required).
fortimail.users.maps.listList User MapsCRead-onlyIdempotent
Purpose: GET /v1/user-maps.
Side effects: None (read-only).
Inputs: no named parameters.
fortimail.users.maps.updateUpdate User MapBIdempotent
Purpose: PUT /v1/user-maps/{key}.
Side effects: Flushes MCP cache.
Inputs: key (required), settings (required).
fortimail.users.updateUpdate Mail UserAIdempotent
Purpose: PUT /v1/domains/{domain}/users/{key}.
Side effects: Flushes MCP cache.
Inputs: key (required), domain (required), settings (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 56 tools
Most tools map clearly to distinct resource/action pairs thanks to hierarchical namespaces like domains, users, queue, and reports. However, some overlaps remain, such as queue.list vs queue.search and multiple reports.generate.* variants, and dead/legacy tools like queue.download and auth.logout add confusion.
All tool names consistently use the fortimail.* dot-namespaced lower_snake_case convention with resource-then-action structure. Variations like domains.info.get still follow the same predictable pattern.
56 tools is heavy for an MCP surface, well beyond the typical 3-15 range and past the 25+ threshold that creates selection overhead. Although many are grouped CRUD variants for distinct resources, the count is excessive for practical agent use.
Core administrative coverage is strong: CRUD for domains, domain info, users, user maps, multiple profile types, queue operations, reports, logs, and SMTP config. Minor gaps include the non-exposed queue.download tool, legacy auth.logout, and absence of broader FortiMail policy/system operations.
Maintenance
Related MCP Connectors
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
AI agents read & send email, manage mailboxes, domains and webhooks via the QMailing API.
Email for AI agents — send, receive as a webhook, manage domains, templates, routing.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables complete management of Mailcow email servers through 20 MCP tools including domain management, mailbox operations, email sending, queue management, sync jobs, and system monitoring. Provides AI models with full control over email server infrastructure through secure API integration.12MIT
- AlicenseBqualityAmaintenanceEnables AI assistants to interact with FortiManager for centralized firewall policy management, device provisioning, and network configuration through the FortiManager JSON-RPC API.25410MIT
- AlicenseCqualityCmaintenanceProvides AI assistants with access to PurelyMail's email management API, enabling user, domain, routing, and billing management through natural language.19106 npm14MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.MIT