Skip to main content
Glama
fortimail-mcp-server

fortimail-mcp-server

by Lynsoft

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 codegen regenerates 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=false only when appropriate

  • Dual 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"

fortimail.engine.status

Queue triage

"List the incoming queue, then show full headers for mkey …"

fortimail.queue.list, fortimail.queue.view

Redirect stuck mail

"Search the deferred queue for recipient X, reroute to backup.example.com"

fortimail.queue.search, fortimail.queue.reroute

Log investigation

"List elog files, download the segment …"

fortimail.logs.list, fortimail.logs.download

Reporting

"List reports, trigger mail stats for task Daily_Stats"

fortimail.reports.list, fortimail.reports.generate.mail_stats

Security model

Mode

Notes

stdio

MCP runs on the operator machine. FORTIMAIL_ENGINE_API_KEY is process env — not passed to the model in normal tool flows.

HTTP

Protect POST /mcp with MCP_HTTP_BEARER_TOKEN and/or MCP_HTTP_API_KEY when not on localhost.

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 test

Required environment:

FORTIMAIL_ENGINE_URL=https://your-engine.example.com/v1
FORTIMAIL_ENGINE_API_KEY=fme_your_key

Example .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 cert

Run:

pnpm start
# HTTP + MCP auth
TRANSPORT=http PORT=3000 MCP_HTTP_BEARER_TOKEN=secret pnpm start

Environment variables

Variable

Required

Default

Description

FORTIMAIL_ENGINE_URL

Yes

—

Engine base URL including /v1

FORTIMAIL_ENGINE_API_KEY

Yes

—

Bearer token (fme_...)

FORTIMAIL_VERIFY_CERT

No

verify

Set false to skip TLS verification (dev only)

FORTIMAIL_CACHE_BACKEND

No

memory

memory or redis

REDIS_URL

No

redis://127.0.0.1:6379

Redis URL

TRANSPORT

No

stdio

stdio or http

PORT

No

3000

HTTP port

MCP_HTTP_HOST

No

0.0.0.0

Bind address for HTTP

MCP_HTTP_BEARER_TOKEN

No

—

If set, POST /mcp requires Authorization: Bearer

MCP_HTTP_API_KEY

No

—

If set, POST /mcp may use X-API-Key

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 as FORTIMAIL_ENGINE_URL with /v1 stripped), 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

POST /mcp with @modelcontextprotocol/sdk StreamableHTTPServerTransport (SSE text/event-stream responses — not single JSON)

Auth

If you set MCP_HTTP_BEARER_TOKEN, clients must send the same secret. Accepted: Authorization: Bearer …, header X-MCP-Bearer-Token (Smithery session x-from), or query ?mcp_bearer_token=

401 for missing auth

Unauthenticated POST /mcp returns 401 with WWW-Authenticate: Bearer realm="fortimail-mcp" (not 403)

Config schema

smithery-config-schema.json — republish with --config-schema "$(cat smithery-config-schema.json)"

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

  • Description: MCP client for FortiMail Engine API — domains, users, profiles, queue, reports, logs, SMTP

  • Required env (process): FORTIMAIL_ENGINE_URL, FORTIMAIL_ENGINE_API_KEY

  • Transports: stdio, Streamable HTTP (POST /mcp streams SSE; GET /mcp returns 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>, or

  • Header: X-MCP-Bearer-Token: <MCP_HTTP_BEARER_TOKEN> (matches Smithery mcp_bearer_token / x-mcp-bearer-token), or

  • Query: ?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.json may 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.delete

  • fortimail.domains.info.get / fortimail.domains.info.update

Users (10 tools)

  • Mail users: fortimail.users.list / .get / .create / .update / .delete

  • User 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.js

Development

See CONTRIBUTING.md. Run pnpm test before submitting changes. After updating openapi/openapi.json, run pnpm run codegen.

Available Tools

56 tools
fortimail.auth.logoutFortiMail Logout (no-op)A
Read-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 CacheA
Idempotent

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 DomainA
Destructive

Purpose: Delete a domain (DELETE /v1/domains/{key}). Inputs: domain. Side effects: Destructive; flushes MCP cache.

Inputs: domain (required).

fortimail.domains.getGet Domain SettingsB
Read-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 InfoC
Read-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 InfoA
Idempotent

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 DomainsA
Read-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 SettingsB
Idempotent

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 StatusA
Read-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 FileC
Read-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 FilesC
Read-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 ProfileC
Destructive

Purpose: Delete GeoIP Profile.

Inputs: key (required).

fortimail.profiles.geoip.getGet GeoIP ProfileC
Read-onlyIdempotent

Purpose: Get one GeoIP Profile.

Inputs: key (required).

fortimail.profiles.geoip.listList GeoIP ProfilesB
Read-onlyIdempotent

Purpose: List GeoIP Profile profiles via the engine. Side effects: None (read-only).

Inputs: no named parameters.

fortimail.profiles.geoip.updateUpdate GeoIP ProfileC
Idempotent

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 ProfileC
Destructive

Purpose: Delete IMAP Auth Profile.

Inputs: key (required), domain (required).

fortimail.profiles.imap_auth.getGet IMAP Auth ProfileC
Read-onlyIdempotent

Purpose: Get one IMAP Auth Profile.

Inputs: key (required), domain (required).

fortimail.profiles.imap_auth.listList IMAP Auth ProfilesC
Read-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 ProfileC
Idempotent

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 ProfileC
Destructive

Purpose: Delete Notification Profile.

Inputs: key (required), domain (required).

fortimail.profiles.notification.getGet Notification ProfileB
Read-onlyIdempotent

Purpose: Get one Notification Profile.

Inputs: key (required), domain (required).

fortimail.profiles.notification.listList Notification ProfilesC
Read-onlyIdempotent

Purpose: List Notification Profile profiles via the engine. Side effects: None (read-only).

Inputs: domain (required).

fortimail.profiles.notification.updateUpdate Notification ProfileC
Idempotent

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 ProfileC
Destructive

Purpose: Delete SMTP Auth Profile.

Inputs: key (required), domain (required).

fortimail.profiles.smtp_auth.getGet SMTP Auth ProfileC
Read-onlyIdempotent

Purpose: Get one SMTP Auth Profile.

Inputs: key (required), domain (required).

fortimail.profiles.smtp_auth.listList SMTP Auth ProfilesC
Read-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 ProfileD
Idempotent

Purpose: Update SMTP Auth Profile.

Inputs: key (required), domain (required), settings (required).

fortimail.queue.deleteDelete Queued MailB
Destructive

Purpose: DELETE /v1/queue with confirmation header (see engine docs). Side effects: Destructive.

Inputs: mail_keys (required), queue_type (required).

fortimail.queue.downloadDownload Queued MailD
Read-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 QueueC
Read-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 QueueB
Read-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 MailC
Read-onlyIdempotent

Purpose: GET /v1/queue/view.

Inputs: mail_key (required), account_type (required), open_method.

fortimail.reports.deleteDelete ReportsC
Destructive

Purpose: DELETE /v1/reports with query params.

Inputs: report_keys (required), domain, report_class.

fortimail.reports.downloadDownload ReportC
Read-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 ReportsC
Read-onlyIdempotent

Purpose: GET /v1/reports.

Inputs: domain, page_size, start_index, report_class.

fortimail.smtp.config.getGet SMTP ConfigurationC
Read-onlyIdempotent

Purpose: GET /v1/smtp-config.

Inputs: no named parameters.

fortimail.smtp.config.updateUpdate SMTP ConfigurationD
Idempotent

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 UserA
Destructive

Purpose: DELETE /v1/domains/{domain}/users/{key}. Side effects: Flushes MCP cache.

Inputs: key (required), domain (required).

fortimail.users.getGet Mail UserB
Read-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 UsersA
Read-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 MapA
Destructive

Purpose: DELETE /v1/user-maps/{key}. Side effects: Flushes MCP cache.

Inputs: key (required).

fortimail.users.maps.getGet User MapA
Read-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 MapsC
Read-onlyIdempotent

Purpose: GET /v1/user-maps. Side effects: None (read-only).

Inputs: no named parameters.

fortimail.users.maps.updateUpdate User MapB
Idempotent

Purpose: PUT /v1/user-maps/{key}. Side effects: Flushes MCP cache.

Inputs: key (required), settings (required).

fortimail.users.updateUpdate Mail UserA
Idempotent

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

    C2.8/5.0

    Scored across 56 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      12
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Provides AI assistants with access to PurelyMail's email management API, enabling user, domain, routing, and billing management through natural language.
      19
      106 npm
      14
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with email accounts via IMAP and SMTP, supporting mailbox listing, email search, retrieval, sending, and management.
      MIT