FortiAnalyzer MCP Server

A Python Model Context Protocol server for the FortiAnalyzer JSON-RPC API. It provides structured tools for system health, ADOM and device inventory, alerts, reports, LogView searches, and documented long-tail read endpoints.

The bundled offline catalog contains searchable factual metadata derived from the public FortiAnalyzer JSON-RPC API documentation. It includes generated summaries and links back to each source page; the source documentation itself is not redistributed in this repository. See NOTICE for provenance and licensing details.

The searchable catalog preserves the guide's published endpoint paths. Endpoint compatibility can vary by appliance release, so validate the tools you plan to use in a non-production environment first.

This is an independent project and is not affiliated with or endorsed by Fortinet. Fortinet and FortiAnalyzer are trademarks of Fortinet, Inc.

Highlights

• API-key and username/password session authentication

• Secure TLS verification by default, with custom CA support

• Lazy, concurrency-safe login and one read retry after documented session expiry (-10)

• Bounded LogView submit/poll/fetch/cleanup workflows

• Structured MCP output with request and endpoint metadata

• Offline API-document metadata search plus an opt-in generic read tool

• Server-managed credentials and session IDs are never exposed in tool schemas or server-generated metadata

• Generic state-changing access disabled by default

• stdio, Streamable HTTP, and SSE transports

Related MCP server: Zabbix MCP Server

Requirements

• Python 3.10 or newer

• Network access to a FortiAnalyzer appliance

• A least-privileged FortiAnalyzer API user

• A FortiAnalyzer release that supports the selected JSON-RPC endpoints

Install

git clone https://github.com/forticrevs/fortianalyzer-mcp.git
cd fortianalyzer-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

Copy the example environment file and configure one authentication method:

cp .env.example .env

API-key authentication is preferred for long-running automation:

FAZ_HOST=https://fortianalyzer.example.com
FAZ_API_KEY=replace-with-a-secret-from-your-secret-store
FAZ_VERIFY_SSL=true

Session authentication is also supported:

FAZ_HOST=https://fortianalyzer.example.com
FAZ_USERNAME=mcp-readonly
FAZ_PASSWORD=replace-with-a-secret-from-your-secret-store
FAZ_VERIFY_SSL=true

Do not commit .env; it is ignored by Git.

Run the stdio server:

fortianalyzer-mcp

An MCP client can launch that executable directly. A representative client configuration is:

{
  "mcpServers": {
    "fortianalyzer": {
      "command": "/absolute/path/to/.venv/bin/fortianalyzer-mcp",
      "env": {
        "FAZ_HOST": "https://fortianalyzer.example.com",
        "FAZ_API_KEY": "${FAZ_API_KEY}",
        "FAZ_VERIFY_SSL": "true"
      }
    }
  }
}

Environment interpolation depends on the MCP client. If it is unsupported, use the client's secret facility or arrange for the server process to inherit the variables.

Tools

faz_raw_write is registered only when FAZ_ENABLE_WRITE_TOOLS=true. It requires confirm=true, cannot call authentication or reboot endpoints, and does not automatically replay a mutation after session expiry or an ambiguous transport failure. The confirmation argument and MCP annotations are not an authorization or human-approval boundary. Enabling this tool grants connected clients broad mutation capability within the FortiAnalyzer account's permissions; use a separate least-privileged account and an external approval control. Keep it disabled for read-only deployments.

Log search behavior

Device scope is always explicit. Use a concrete list such as ["branch-fgt-01"]; use ["All_FortiGate"] only intentionally.

Relative searches default to the last hour. Absolute times must be paired, FortiAnalyzer-local timestamps:

2025-01-15 09:00:00

By default:

• a specific-device search is limited to 24 hours;

• an all-device search is limited to 1 hour;

• one tool result is limited to 200 rows;

• LogView fetch pages never exceed the appliance limit of 500 rows;

• at most eight LogView searches can be active or starting concurrently;

• the convenience workflow times out after 30 seconds;

• task deletion is attempted after completion, timeout, errors, and server shutdown; failed cleanup remains tracked for a later shutdown retry.

For pagination, start a task and retrieve each required offset. A completed full page does not prove that all rows were consumed, so the server conservatively keeps that task alive even when cleanup_when_done=true. Set cleanup_when_done=false while managing pages explicitly, then call faz_cancel_log_search. The convenience faz_search_logs workflow intentionally returns one page and always attempts to release its task.

Configuration

For self-signed appliance certificates, install the issuing CA and set FAZ_CA_BUNDLE. FAZ_VERIFY_SSL=false is available for development but should not be used in production.

Network transports do not add client authentication to the MCP endpoint. Keep the default loopback binding or place the server behind an authenticated, TLS-protected gateway.

Browser clients must be explicitly allowed. For example:

FAZ_MCP_ALLOWED_ORIGINS=http://model.example.test,https://another-ui.example

Origins are exact HTTP(S) origins without paths or trailing slashes. A terminal port wildcard such as http://model.example.test:* is supported. The setting drives both DNS-rebinding validation and CORS/preflight responses. Localhost origins remain allowed automatically. If a proxy forwards a non-local Host header, allow that separately, for example FAZ_MCP_ALLOWED_HOSTS=model.example.test,model.example.test:*. These allowlists are request-validation controls, not client authentication.

Development

Install the development extra and run the test suite:

python -m pip install -e '.[dev]'
pytest

Rebuild the offline catalog from a documentation tree you are authorized to use:

python scripts/build_catalog.py \
  --source /path/to/fortianalyzer-api-docs \
  --output src/fortianalyzer_mcp/data/api_catalog.json

The automated suite uses mocked HTTP transports and does not require an appliance. Validate against your appliance because releases can differ in endpoint-specific request and response fields.

faz_raw_get accepts any syntactically valid appliance-local path except blocked authentication paths; catalog membership is guidance, not an enforced allowlist. It prevents request-field overrides and always sends JSON-RPC get, but returns endpoint data without field-level redaction or a generic response-size cap. Use a least-privileged account, call only trusted endpoints, and pass endpoint-specific limit, range, or field-selection parameters.