FortiAnalyzer MCP Server

FortiAnalyzer MCP Server

A Python Model Context Protocol server for the FortiAnalyzer JSON-RPC API. Itprovides 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 fromthe publicFortiAnalyzer JSON-RPC API documentation.It includes generated summaries and links back to each source page; the sourcedocumentation itself is not redistributed in this repository. SeeNOTICE for provenance and licensing details.

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

This is an independent project and is not affiliated with or endorsed byFortinet. 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 sessionexpiry (-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 schemasor server-generated metadata
• Generic state-changing access disabled by default
• stdio, Streamable HTTP, and SSE transports

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 clientconfiguration 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, usethe client's secret facility or arrange for the server process to inherit thevariables.

Tools

faz_raw_write is registered only when FAZ_ENABLE_WRITE_TOOLS=true. Itrequires confirm=true, cannot call authentication or reboot endpoints, anddoes not automatically replay a mutation after session expiry or an ambiguoustransport failure. The confirmation argument and MCP annotations are not anauthorization or human-approval boundary. Enabling this tool grants connectedclients broad mutation capability within the FortiAnalyzer account'spermissions; use a separate least-privileged account and an external approvalcontrol. 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 servershutdown; failed cleanup remains tracked for a later shutdown retry.

For pagination, start a task and retrieve each required offset. A completed fullpage does not prove that all rows were consumed, so the server conservativelykeeps that task alive even when cleanup_when_done=true. Setcleanup_when_done=false while managing pages explicitly, then callfaz_cancel_log_search. The convenience faz_search_logs workflow intentionallyreturns one page and always attempts to release its task.

Configuration

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

Network transports do not add client authentication to the MCP endpoint. Keepthe 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 terminalport wildcard such as http://model.example.test:* is supported. The setting drivesboth DNS-rebinding validation and CORS/preflight responses. Localhost originsremain allowed automatically. If a proxy forwards a non-local Host header,allow that separately, for exampleFAZ_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 touse:

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 anappliance. Validate against your appliance because releases can differ inendpoint-specific request and response fields.

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