FortiManager MCP Server

A Model Context Protocol (MCP) server for FortiManager JSON-RPC API. This server enables AI assistants like Claude to interact with FortiManager for centralized firewall policy management, device provisioning, and network configuration.

Note: This is an independent open-source project and is not affiliated with, endorsed by, or supported by Fortinet, Inc. FortiManager is a trademark of Fortinet, Inc.

Disclaimer: This MCP server can create, modify, and delete configurations on FortiManager. Misuse or misconfiguration can impact production networks. Use at your own risk. Always test in a non-production environment first and ensure appropriate ADOM permissions are configured.

Overview

This MCP server provides a comprehensive interface to FortiManager's capabilities, allowing AI assistants to:

• Create and manage firewall policies and policy packages

• Configure firewall objects (addresses, services, VIPs)

• Add, provision, and manage FortiGate devices

• Execute CLI scripts on managed devices

• Configure provisioning and SD-WAN templates

• Monitor tasks and installations

• Manage ADOMs and workspace locking

Features

Requirements

• Python: 3.12 or higher

• FortiManager: 7.x with JSON-RPC API access enabled

• Authentication: API token (recommended) or username/password

• Network: HTTPS access to FortiManager management interface

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/rstierli/fortimanager-mcp.git
cd fortimanager-mcp

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv sync

Using pip

# Clone the repository
git clone https://github.com/rstierli/fortimanager-mcp.git
cd fortimanager-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install package
pip install -e .

Using Docker

Pre-built images are available on GitHub Container Registry:

docker pull ghcr.io/rstierli/fortimanager-mcp:latest

Quick start with Docker Compose:

# docker-compose.yml
services:
  fortimanager-mcp:
    image: ghcr.io/rstierli/fortimanager-mcp:latest
    container_name: fortimanager-mcp
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env
    environment:
      - MCP_SERVER_MODE=http
      - MCP_SERVER_HOST=0.0.0.0
      - MCP_SERVER_PORT=8000
      - FORTIMANAGER_HOST=your-fmg-hostname
      # Keep TLS verification on; import the FortiManager CA for self-signed
      # certs. FORTIMANAGER_VERIFY_SSL=false disables MITM protection.
      - FORTIMANAGER_VERIFY_SSL=true
      - DEFAULT_ADOM=root
      - FMG_TOOL_MODE=full
      - LOG_LEVEL=INFO

Create a .env file for secrets (not tracked in git):

# .env
FORTIMANAGER_API_TOKEN=your-api-token
MCP_AUTH_TOKEN=your-secret-bearer-token  # optional, enables HTTP auth

chmod 600 .env
docker compose up -d

Verify the server is running:

curl http://localhost:8000/health
# {"status": "healthy", "service": "fortimanager-mcp", "fortimanager_connected": true}

Configuration

Environment Variables

Create a .env file from the example:

cp .env.example .env

Edit .env with your FortiManager settings:

# FortiManager Connection (Required)
FORTIMANAGER_HOST=192.168.1.100

# Authentication Option 1: API Token (Recommended)
FORTIMANAGER_API_TOKEN=your-api-token-here

# Authentication Option 2: Username/Password
# FORTIMANAGER_USERNAME=admin
# FORTIMANAGER_PASSWORD=your-password

# SSL Verification — keep this TRUE. For self-signed FortiManager certs,
# import the FortiManager CA into your trust store instead of disabling it
# (see docs/SETUP_GUIDE.md "Trusting the FortiManager CA"). Setting this to
# false disables TLS verification and exposes the connection to MITM attacks.
FORTIMANAGER_VERIFY_SSL=true

# Request Settings
FORTIMANAGER_TIMEOUT=30
FORTIMANAGER_MAX_RETRIES=3

# Logging
LOG_LEVEL=INFO  # DEBUG for troubleshooting

# Tool Loading Mode (important for context window optimization)
FMG_TOOL_MODE=full  # or "dynamic" for ~90% context reduction

# Default ADOM (optional - defaults to "root")
DEFAULT_ADOM=root

# HTTP Authentication (optional, recommended for Docker/HTTP deployments)
# MCP_AUTH_TOKEN=your-secret-token

# MCP Server Settings (for HTTP/Docker mode)
# MCP_SERVER_MODE=http     # "http" for Docker, "stdio" for Claude Desktop, "auto" to detect
# MCP_SERVER_HOST=0.0.0.0  # Bind address (0.0.0.0 for Docker)
# MCP_SERVER_PORT=8000      # Server port

# Allowed Host headers for HTTP/Docker deployments (optional)
# Set to the value clients use in their connection URL — NOT the client's IP.
# The MCP SDK rejects non-localhost Host headers by default for DNS rebinding protection.
# Examples: ["mcp.example.com"], ["10.1.5.62:8000"], or wildcard ["10.1.5.62:*"]
# MCP_ALLOWED_HOSTS=["mcp.example.com"]

# Safety Guardrails (optional - strict by default)
# FMG_SCRIPT_SAFETY=strict    # Block dangerous CLI commands in scripts (factory-reset, reboot, etc.)
# FMG_POLICY_SAFETY=strict    # Block overly permissive policies (srcaddr=all + dstaddr=all + accept)

Tool Loading Modes

FortiManager MCP supports two tool loading modes to optimize context window usage:

Full Mode (default): All 102 tools are loaded at startup. Best when you have sufficient context window and need immediate access to all FortiManager operations.

Dynamic Mode: Only lightweight discovery tools are loaded:

• find_fortimanager_tool(operation) - Search for tools by keyword

• list_fortimanager_categories() - List tool categories

• execute_fortimanager_tool(name, params) - Execute any tool by name

• health_check() - Server health status

To enable dynamic mode:

FMG_TOOL_MODE=dynamic

Default ADOM

The DEFAULT_ADOM environment variable sets the default Administrative Domain (ADOM) for all FortiManager operations. When a tool is called without specifying an ADOM, this value is used.

DEFAULT_ADOM=root  # default value

This is particularly useful when:

• Your FortiManager only uses a single ADOM

• Most of your work is within one specific ADOM

• You want to avoid repeatedly specifying the ADOM in each tool call

If not set, defaults to root (the global ADOM).

Generating an API Token

1. Log into FortiManager web interface

2. Go to System Settings > Admin > Administrators

3. Edit your admin user or create a new one

4. Under JSON API Access, click Regenerate or New API Key

5. Copy the generated token

Running the Server

Standalone Mode

# Using the installed command
fortimanager-mcp

# Or using Python module
python -m fortimanager_mcp

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fortimanager": {
      "command": "/path/to/fortimanager-mcp/.venv/bin/fortimanager-mcp",
      "env": {
        "FORTIMANAGER_HOST": "your-fmg-hostname",
        "FORTIMANAGER_API_TOKEN": "your-api-token",
        "FORTIMANAGER_VERIFY_SSL": "true",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Note: Use the full path to the fortimanager-mcp executable in your virtual environment.

Claude Code Integration

Add to ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "fortimanager": {
      "command": "/path/to/fortimanager-mcp/.venv/bin/fortimanager-mcp",
      "env": {
        "FORTIMANAGER_HOST": "your-fmg-hostname",
        "FORTIMANAGER_API_TOKEN": "your-api-token",
        "FORTIMANAGER_VERIFY_SSL": "true",
        "DEFAULT_ADOM": "root",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Docker Mode

# Start the server
docker compose up -d

# View logs
docker compose logs -f

# Stop the server
docker compose down

HTTP Mode (Remote Access)

When running in HTTP mode (Docker or standalone with MCP_SERVER_MODE=http), MCP clients connect via the Streamable HTTP transport:

Claude Code (~/.claude/mcp_servers.json):

{
  "mcpServers": {
    "fortimanager": {
      "type": "streamable-http",
      "url": "https://your-mcp-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-auth-token"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "fortimanager": {
      "type": "streamable-http",
      "url": "https://your-mcp-host.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-auth-token"
      }
    }
  }
}

Production Deployment (Reverse Proxy)

For production deployments behind a TLS-terminating reverse proxy:

MCP Client → HTTPS → Reverse Proxy (Traefik/nginx) → HTTP → MCP Container → FortiManager

Key considerations:

1. MCP_ALLOWED_HOSTS — The MCP SDK validates the Host header to prevent DNS rebinding attacks. By default only localhost and 127.0.0.1 are accepted. Set this to the value clients put in their connection URL (NOT the client's IP):

   # Reverse-proxy hostname (Traefik/nginx):
   MCP_ALLOWED_HOSTS=["mcp.example.com"]
   # Direct Docker exposure on IP+port:
   MCP_ALLOWED_HOSTS=["10.1.5.62:8000"]
   # Port wildcard (any port on the host):
   MCP_ALLOWED_HOSTS=["10.1.5.62:*"]

2. MCP_AUTH_TOKEN — Always set a Bearer token for HTTP deployments:

   MCP_AUTH_TOKEN=$(openssl rand -hex 32)

3. Secrets management — Keep API tokens and auth tokens in an env_file (.env), not inline in docker-compose.yml.

Example with Traefik:

services:
  fortimanager-mcp:
    image: ghcr.io/rstierli/fortimanager-mcp:latest
    container_name: fortimanager-mcp
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    env_file:
      - .env
    environment:
      - MCP_SERVER_MODE=http
      - MCP_SERVER_HOST=0.0.0.0
      - MCP_SERVER_PORT=8000
      - FORTIMANAGER_HOST=your-fmg-hostname
      # Keep TLS verification on; import the FortiManager CA for self-signed
      # certs. FORTIMANAGER_VERIFY_SSL=false disables MITM protection.
      - FORTIMANAGER_VERIFY_SSL=true
      - MCP_ALLOWED_HOSTS=["mcp.example.com"]
      - DEFAULT_ADOM=root
      - FMG_TOOL_MODE=full
      - LOG_LEVEL=INFO
    networks:
      - frontend
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.fmg-mcp-secure.entrypoints=https"
      - "traefik.http.routers.fmg-mcp-secure.rule=Host(`mcp.example.com`)"
      - "traefik.http.routers.fmg-mcp-secure.tls=true"
      - "traefik.http.services.fmg-mcp.loadbalancer.server.port=8000"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  frontend:
    external: true

Available Tools (102 tools)

System Tools (17 tools)

Device Management Tools (12 tools)

Policy Tools (15 tools)

Object Tools (24 tools)

Script Tools (12 tools)

Template Tools (15 tools)

SD-WAN Tools (7 tools)

Usage Examples

Policy Management

"List all firewall policies in the 'default' package"
"Create a new policy to allow HTTP traffic from internal to wan1"
"Move policy 10 before policy 5 in the default package"
"Install the branch-policy package to FGT-01"

Object Management

"Create an address object for the web server at 192.168.10.10"
"List all address groups in the root ADOM"
"Create a service for TCP port 8443"
"Search for all objects containing 'web' in the name"

Device Management

"List all devices in the root ADOM"
"Add a new FortiGate device at 10.0.0.1"
"Get the connection status for FGT-01"
"Show the VDOMs configured on FGT-01"

Script Execution

"List all CLI scripts in the root ADOM"
"Create a backup script that runs 'execute backup config ftp'"
"Execute the backup script on FGT-01"
"Show the latest script execution log for FGT-01"

Template Management

"List all system templates in the ADOM"
"Assign the 'Branch-Template' to FGT-01"
"Show available SD-WAN templates"
"Validate the template against device FGT-01"

System Operations

"What is the FortiManager system status?"
"Lock the root ADOM for editing"
"Show all running tasks"
"Wait for task 123 to complete"

Architecture

fortimanager-mcp/
├── src/fortimanager_mcp/
│   ├── api/
│   │   └── client.py          # FortiManager API client (JSON-RPC)
│   ├── tools/
│   │   ├── system_tools.py    # System, ADOM, task management
│   │   ├── dvm_tools.py       # Device management tools
│   │   ├── policy_tools.py    # Policy and package tools
│   │   ├── object_tools.py    # Address, service objects
│   │   ├── script_tools.py    # CLI script tools
│   │   ├── template_tools.py  # Provisioning templates
│   │   └── sdwan_tools.py     # SD-WAN templates
│   ├── utils/
│   │   ├── config.py          # Configuration management
│   │   └── errors.py          # Error handling
│   └── server.py              # MCP server implementation
├── tests/                     # Test suite (190+ tests)
├── docs/                      # API documentation
├── .env.example               # Example configuration
├── pyproject.toml             # Project configuration
├── Dockerfile                 # Container image definition
└── docker-compose.yml         # Container orchestration

API Reference

The server communicates with FortiManager using the JSON-RPC API over HTTPS. All requests are sent to the /jsonrpc endpoint.

Supported FortiManager Versions

• FortiManager 7.0.x

• FortiManager 7.2.x

• FortiManager 7.4.x

• FortiManager 7.6.x (primary development target)

Authentication Methods

1. API Token (Recommended)

   • More secure, no session management

   • Tokens can be revoked without changing passwords

   • Works with FortiManager 7.0+

2. Username/Password

   • Traditional session-based authentication

   • Session automatically managed by the client

Troubleshooting

Enable Debug Logging

Set LOG_LEVEL=DEBUG in your environment to see detailed API requests and responses:

LOG_LEVEL=DEBUG fortimanager-mcp

Common Issues

Connection Failed

• Verify FortiManager hostname/IP is correct

• Check network connectivity and firewall rules

• Ensure HTTPS port (443) is accessible

Authentication Failed

• Verify API token or credentials are correct

• Check if the admin account has API access enabled

• Ensure the account has sufficient permissions

SSL Certificate Errors

• For self-signed FortiManager certs, import the FortiManager CA certificate into your trust store and keep FORTIMANAGER_VERIFY_SSL=true (see SETUP_GUIDE.md → "Trusting the FortiManager CA")

• For production, use valid SSL certificates signed by a trusted CA

• Last resort only: FORTIMANAGER_VERIFY_SSL=false disables TLS verification and exposes the connection to man-in-the-middle attacks — avoid in production

ADOM Locked

• Another user may have the ADOM locked

• Use unlock_adom to release the lock (requires permissions)

• Check workspace mode settings in FortiManager

MCP Transport Issues

Invalid Host header (HTTP/Docker mode)

Symptom — server logs show:

mcp.server.transport_security - WARNING - Invalid Host header: 10.x.y.z:8000
INFO:     ... "POST /mcp HTTP/1.1" 421 Misdirected Request

Cause: the MCP SDK validates the Host header for DNS rebinding protection. By default only localhost and 127.0.0.1 are accepted. The header value is whatever the client puts in its connection URL — not the client's IP.

Fix: add the URL value (with port, if used) to MCP_ALLOWED_HOSTS:

# If the client connects to http://10.1.5.62:8000/mcp:
MCP_ALLOWED_HOSTS=["10.1.5.62:8000"]
# Or use a port wildcard to allow any port on that host:
MCP_ALLOWED_HOSTS=["10.1.5.62:*"]
# For a reverse-proxy hostname:
MCP_ALLOWED_HOSTS=["mcp.example.com"]

PermissionError: pyvenv.cfg (macOS stdio mode)

Symptom — Claude Desktop MCP logs show:

Fatal Python error: init_import_site: Failed to import the site module
PermissionError: [Errno 1] Operation not permitted: '.../.venv/pyvenv.cfg'

Cause: macOS TCC (Transparency, Consent, Control) blocks Claude Desktop from launching executables from inside ~/Documents, ~/Desktop, or ~/Downloads.

Fix (preferred): move the project out of those folders, recreate the venv, and update Claude Desktop's MCP config to the new path:

mv ~/Documents/mcp ~/mcp
cd ~/mcp/fortimanager-mcp
rm -rf .venv && uv sync
# Then update the "command" path in claude_desktop_config.json

Fix (alternative): grant Claude Desktop Full Disk Access — System Settings → Privacy & Security → Full Disk Access → add Claude. Broader permission; only use if relocation isn't feasible.

Viewing Logs

Claude Desktop MCP Server Logs:

• macOS: ~/Library/Logs/Claude/mcp-server-fortimanager.log

• Windows: %APPDATA%\Claude\logs\mcp-server-fortimanager.log

Development

Running Tests

The project includes 190+ tests covering all tool modules, error handling, and validation logic.

# Install dev dependencies
uv sync --all-extras

# Run all unit tests
pytest

# Run with coverage report
pytest --cov=src/fortimanager_mcp --cov-report=html

# Run specific test file
pytest tests/test_policy_tools.py -v

# Run tests with verbose output
pytest -v

Integration Tests

Integration tests require a real FortiManager instance and are not run in CI.

# Set up environment
export FORTIMANAGER_HOST=your-fmg-host
export FORTIMANAGER_API_TOKEN=your-token
# Keep verification on; import the FortiManager CA for self-signed certs.
export FORTIMANAGER_VERIFY_SSL=true

# Run integration tests (requires live FMG)
pytest tests/integration/ -v

Note: Integration tests are verified against FortiManager 7.6.2. Some features may behave differently on older versions.

CI Workflow

The project uses GitHub Actions for continuous integration:

• Linting: ruff check on all source files

• Type checking: mypy with strict mode

• Unit tests: pytest with coverage reporting

• Python versions: 3.12+

All CI checks must pass before merging pull requests.

Code Quality

# Linting
ruff check src/

# Type checking
mypy src/

# Formatting
ruff format src/

Security Considerations

HTTP Authentication

When running in HTTP mode (Docker), you can secure the MCP endpoint with Bearer token authentication:

# Set in .env or environment
MCP_AUTH_TOKEN=your-secret-token

When configured, all HTTP requests (except /health) must include the Authorization: Bearer <token> header. If not set, the server runs without authentication (backwards compatible).

Environment File Permissions

Protect your .env files containing API tokens:

chmod 600 .env .env.*

Dynamic Tool Dispatch Security

In dynamic mode, the tool dispatcher validates tool names:

• Rejects private/internal functions (underscore-prefixed names)

• Validates that resolved attributes are callable

• Error responses never include request parameters (prevents credential leakage)

Safety Guardrails

The MCP server includes built-in safety checks to prevent accidental damage to managed infrastructure. Both are enabled by default.

Script Content Safety (FMG_SCRIPT_SAFETY)

Blocks dangerous CLI commands in create_script and update_script:

Handles FortiOS abbreviations (exec for execute) and case variations.

FMG_SCRIPT_SAFETY=strict    # Default: block dangerous commands
FMG_SCRIPT_SAFETY=disabled  # Allow all commands (use with extreme caution)

Policy Permissiveness Safety (FMG_POLICY_SAFETY)

Blocks overly permissive firewall policies in create_firewall_policy and update_firewall_policy. Detects policies where srcaddr=all + dstaddr=all + action=accept, which allows unrestricted traffic.

FMG_POLICY_SAFETY=strict    # Default: block overly permissive policies
FMG_POLICY_SAFETY=warn      # Allow but include warning in response
FMG_POLICY_SAFETY=disabled  # Allow all policies

General Security

• API Tokens: Store tokens securely, never commit to version control

• SSL Verification: Enable SSL verification in production environments

• Least Privilege: Use FortiManager accounts with minimal required permissions

• Network Security: Restrict access to FortiManager management interface

• Workspace Locking: Use ADOM locking to prevent concurrent modifications

• Credential Sanitization: Device credentials are automatically stripped from API responses

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to submit bug reports, feature requests, and pull requests.

License

MIT License - See LICENSE file for details.

Acknowledgments

• Anthropic for the Model Context Protocol

• Fortinet for FortiManager

• pyfmg library for FortiManager/FortiAnalyzer API

• jmpijll/fortimanager-mcp - Architectural inspiration

Related Projects

• fortianalyzer-mcp - MCP server for FortiAnalyzer with 70+ tools

• pyfmg - FortiManager/FortiAnalyzer Python library

Author

Roland Stierli