Knight FortiGate Multi-Device MCP

Manage FortiGate firewalls from an MCP-compatible AI client, with a terminal wizard for local device enrollment, operating-system credential storage, read-only connectivity checks, and client integration.

Author and maintainer

Ehsan Emad — CyberKnightLabs, creator of Networking With Ehsan and TechLoungeCast.

• Networking With Ehsan

• Cisco Knight Multi-Device

• VMware Knight MCP

Knight adds device enrollment, credential-manager integration and AI client setup to an MIT-licensed FortiOS API server. Required upstream copyright attribution is retained in LICENSE.

Related MCP server: FortiGate MCP Server

Contents

• Purpose and architecture

• Requirements

• Install and verify prerequisites

• Prepare FortiGate API access

• Start the wizard

• Every wizard menu

• Multiple devices

• Manual client configuration

• Tools and functions

• Troubleshooting

• Development and validation

Purpose and architecture

The wizard replaces routine hand editing of connection settings. It collects a device nickname, management address, HTTPS port, VDOM, TLS preferences, timeout and hidden API token. Device metadata is saved locally; the token is stored through Python keyring. Client registrations contain a device selector rather than the token.

The MCP server exposes typed tools for common operations and generic API tools for other FortiOS resources. Available operations depend on firmware, platform, API permissions and VDOM scope. The source targets FortiOS 7.6.x; the existing local deployment was tested against 7.6.6. Generic API access does not guarantee that every endpoint works on every model.

Multi-device model: the wizard holds an inventory of devices. Each client registration starts a separate MCP process selected by FORTIGATE_DEVICE. This release does not switch devices inside a running process or add a device argument to every tool. Separate registrations let several FortiGates coexist in the same client.

The wizard enrolls local metadata and credentials; it does not provision firewall settings. Option 5 sends HTTPS GET requests. MCP tools include write and delete operations: use a read-only FortiGate API profile when you require enforced read-only access. Natural-language instructions alone do not enforce permissions.

Requirements

A headless Linux machine may need a Secret Service backend and an unlocked user session. A missing, locked or plaintext-only keyring is not equivalent to secure OS credential storage. Use keyring diagnose to inspect the configured backend.

Install and verify prerequisites

macOS / Linux

Check what is installed:

python3 --version
python3 -c "import sys; assert sys.version_info >= (3,11), 'Python 3.11+ required'; print('Python version OK')"
git --version
uv --version
command -v python3
command -v git
command -v uv

If uv is missing and Python/pip are available:

python3 -m pip install --user uv

If your Python installation blocks user package installation, install uv using your system package manager. On a Homebrew-managed Mac, for example:

brew install python uv git

Open a new terminal if PATH changes. Clone and install:

git clone https://github.com/CyberKnightLabs/knight-fortigate-multi-device.git
cd knight-fortigate-multi-device
uv sync --locked
uv run python -c "import mcp, httpx, pydantic, dotenv, keyring; print('Dependency imports OK')"
uv run python -m keyring diagnose

Windows PowerShell

py -3 --version
py -3 -c "import sys; assert sys.version_info >= (3,11); print('Python version OK')"
git --version
uv --version
Get-Command py,git,uv

Install Python 3.11+ and Git if missing. With a working Python installation, install uv using:

py -3 -m pip install --user uv

Reopen PowerShell if required, then:

git clone https://github.com/CyberKnightLabs/knight-fortigate-multi-device.git
cd knight-fortigate-multi-device
uv sync --locked
uv run python -c "import mcp, httpx, pydantic, dotenv, keyring; print('Dependency imports OK')"
uv run python -m keyring diagnose

Windows and Linux code paths are provided; this publication was validated locally on macOS, not end-to-end on those operating systems.

Prepare FortiGate API access

Before enrolling a device, collect its management IP or DNS name, HTTPS port, default VDOM and REST API token. Create the API administrator through your FortiOS administration interface, assign a suitable access profile and VDOM access, and restrict trusted source addresses to the MCP host. Exact controls vary by firmware and administrator permissions.

For inventory and troubleshooting only, assign a read-only profile with the required resource access. A broad administrative token enables configuration-changing MCP tools. The token is displayed when created; save it securely and paste it only into the wizard's hidden terminal prompt. Do not paste it into chat, a GitHub issue or screenshots.

Allow the MCP host to reach the management HTTPS service. Use a trusted certificate or provide a PEM CA certificate path in the wizard. Keep TLS verification enabled for normal use. Disabling it skips server identity verification.

A TCP check can establish reachability without a token:

# Replace with your device and actual HTTPS port.
uv run python -c "import socket; s=socket.create_connection(('192.0.2.10',443),5); s.close(); print('TCP reachable')"

This does not test API authorization; option 5 does that after enrollment.

Start the wizard

From the cloned directory on any supported platform:

uv run python manager.py

Alternatively, after dependency synchronization:

uv run knight-fortigate-wizard

Run it in your local terminal, under the same OS user who will run the AI client so both can access the same credential store. The wizard is interactive and must not be configured as the MCP stdio server command.

Recommended first-time sequence:

1. 1 — Set / Edit MCP Location: enter the absolute path of this cloned repository.

2. 2 — Check & Install Prerequisites: verify tools and synchronize dependencies.

3. 3 — Add FortiGate Device: enroll one or more firewalls.

4. 5 — Test FortiGate Connectivity: select a device and verify API access.

5. 6 — One-Click AI Client Integration: select a client and device, inspect the plan and approve the local configuration update.

6. Fully quit and reopen the AI client, then start a new chat and request a read-only system-status or interface query.

Every wizard menu

Option 1: project location

Enter the repository folder itself, not the path to a Python file or virtual environment. It must already exist and contain server.py and pyproject.toml. The saved path is used by prerequisite synchronization and generated client launch commands. Moving the repository later requires updating the location and client registration.

Option 2: prerequisites

Python must be 3.11+ and Git must be available. If uv is absent, the wizard offers python -m pip install --user uv, using its current Python interpreter. It then runs uv sync --directory <project>. This can download dependencies and create or update .venv. A success message indicates dependency synchronization completed, not that a FortiGate connection has been tested.

Option 3: enrollment prompts

Enrollment does not test API connectivity. Run option 5 afterwards. Repeat option 3 for additional devices; duplicate names are rejected.

Option 4: management submenu

Removal does not revoke the API token on the firewall and does not delete a client registration. Device renaming is not supported directly; enroll the desired new nickname and retire the old entry.

Option 5: read-only connection test

Select a registered nickname. The wizard loads its token from keyring, creates an HTTPS connection with the selected certificate settings and issues:

GET /api/v2/monitor/system/status
GET /api/v2/cmdb/system/interface?vdom=<default_vdom>

It reports firmware and serial information returned by the device, authentication failures and interface-read success or failure. A successful interface read is not an independent proof of VDOM isolation. Review warning lines even when the final message says the test completed. Test output can contain identifying device information; redact it before sharing.

Option 6: client integration submenu

Each registration is named fortigate-<device-name>. Repeat for each device/client pair. The plan shows the client config path, selected device, project location and resolved uv executable. Enter y to apply. Configuration backups are created and checked before writing. Tokens are not added to client configuration.

The integration requires an existing, valid client configuration file. Open and initialize the client first. Automatic detection is heuristic: alternate installations and Store-packaged apps may require manual configuration. Existing unrelated MCP registrations are preserved.

Claude can update the same named registration. Codex currently refuses to overwrite an existing registration; remove that specific entry manually after making a backup, then rerun option 6. Older fortigate entries are preserved, so remove a redundant old registration yourself if it connects to the same device.

Reserved options: diagnostics, update, backup and uninstall

Options 7–10 are visible placeholders, not implemented workflows. Use these procedures instead:

• Diagnostics: run the prerequisite commands, keyring diagnosis, option 5 and client-side tool discovery.

• Update: commit or save local edits, then run git pull --ff-only and uv sync --locked from the repository. Restart MCP clients afterwards. This is intended for an installed Git checkout, not an untracked source archive.

• Backup: securely copy the manager JSON and relevant client configuration. The JSON contains device addresses but not tokens. Keyring credentials require their own OS-supported backup or token re-enrollment; copying JSON alone cannot restore them. Integration backups can contain other clients' secrets, so keep them private.

• Uninstall integration: back up the client config, remove only the selected fortigate-<device-name> entry and restart the client. Option 4 can separately remove local enrollment and its token. Revoke the token through FortiGate administration if it is no longer needed.

Multiple devices

Example nicknames LAB-EDGE and BRANCH-EDGE produce two registrations, fortigate-LAB-EDGE and fortigate-BRANCH-EDGE. Each has its own process, credentials, VDOM and TLS settings. Always identify the intended firewall in your AI request and review which server supplies the chosen tool.

Using fortigate-LAB-EDGE, retrieve system status and interface names/IP addresses.
This is read-only. Do not change configuration.

The inventory path is currently fixed for compatibility:

~/.config/fortigate-mcp-manager/config.json

This applies on macOS, Linux and Windows (where ~ is the current user's home). Tokens use keyring service fortigate-mcp-manager, keyed by the exact device nickname. POSIX metadata files are written with restricted permissions; Windows relies on the current user's filesystem protections. Run one wizard instance at a time.

Manual client configuration

Use your absolute uv executable path (command -v uv on macOS/Linux, Get-Command uv on PowerShell), repository path and enrolled device nickname. The runtime entry point is server.py, not manager.py.

Claude Desktop example; merge into existing settings:

{
  "mcpServers": {
    "fortigate-LAB-EDGE": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--directory", "/absolute/path/to/knight-fortigate-multi-device", "python", "server.py"],
      "env": {"FORTIGATE_DEVICE": "LAB-EDGE"}
    }
  }
}

Codex TOML example; use a distinct table name for each device:

[mcp_servers."fortigate-LAB-EDGE"]
command = "/absolute/path/to/uv"
args = ["run", "--directory", "/absolute/path/to/knight-fortigate-multi-device", "python", "server.py"]

[mcp_servers."fortigate-LAB-EDGE".env]
FORTIGATE_DEVICE = "LAB-EDGE"

Use forward slashes in Windows JSON/TOML paths or escape backslashes correctly. The wizard resolves executable paths automatically when detection succeeds.

Detected config locations:

Environment-only compatibility mode

Without FORTIGATE_DEVICE, the server reads FORTIOS_HOST, FORTIOS_API_TOKEN, FORTIOS_VDOM, FORTIOS_VERIFY_SSL and FORTIOS_TIMEOUT from its environment or .env. See .env.example. The compatibility TLS default is false; explicitly enable verification for normal use. Managed mode takes precedence when FORTIGATE_DEVICE is set. Keep .env private and untracked.

HTTP transport

The default is local stdio. An optional HTTP server can be started with:

FORTIGATE_DEVICE=LAB-EDGE MCP_TRANSPORT=streamable-http MCP_PORT=8000 uv run python server.py

This shell syntax is for macOS/Linux; in PowerShell set the same values with $env:NAME='value' before launching. The default bind address is 127.0.0.1, endpoint /mcp. The project does not supply an authenticated public HTTP gateway; keep the listener local unless you provide appropriate external access controls.

Tools and functions

See the generated tool reference for every registered function and its source docstring.

Read-only starting requests:

Get system status from the selected FortiGate.
List all interfaces with their configured IP addresses.
Show the current static routing configuration.
List firewall policies without changing them.

get, list and monitoring reads generally retrieve data; create, update, delete, action and service operations may change state. Inspect the individual function and its HTTP method. Use the firewall API account's permissions to enforce access boundaries.

Troubleshooting

Do not attach tokens, .env, inventory JSON, keyring exports, device response dumps or private client config to issues. Use placeholder addresses such as 192.0.2.10 in shared examples.

Development and validation

uv sync --locked
uv run pytest -q
uv run python -m compileall -q server.py manager.py manager_credentials.py tools

Tests use temporary client configs and mock network/credential operations. They must not enroll real devices or modify firewall configuration. Keep live API writes outside automated checks.

The publication combines the locally working API server and manager. Hardware-specific endpoint coverage and Windows/Linux end-to-end operation require additional validation. Current limitations include one selected device per MCP process, Codex add-only integration, heuristic client detection and reserved menu options 7–10.

MIT licensed; see LICENSE. This project is independent of Fortinet and is not endorsed by Fortinet.