Skip to content

README.md

Latest commit

 

History

History
417 lines (314 loc) · 14 KB

README.md

File metadata and controls

417 lines (314 loc) · 14 KB
Raw

FortiGate MCP Server

Test Lint Security Release

FortiGate MCP Server - A comprehensive Model Context Protocol (MCP) server for managing FortiGate devices. This project provides programmatic access to FortiGate devices and enables integration with MCP-compatible clients such as Claude Desktop, Claude Code, and Cursor.

🚀 Features

FortiGate MCP Server exposes 33 unique tools, 61 total tool-surface registrations across stdio (30) and HTTP (31) transports; 3 create-tools have transport-specific parameter shapes. Covered areas:

  • Device Management: Add, remove, and test connections to FortiGate devices
  • Firewall Management: List, create, update, and delete firewall rules
  • Network Management: Manage address and service objects
  • Routing Management: Manage static routes and interfaces
  • Virtual IP Management: Manage virtual IPs (VIP/DNAT)
  • HTTP Transport: MCP protocol over HTTP using FastMCP
  • Docker Support: Easy installation and deployment
  • MCP Client Integration: Works with Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients

📋 Requirements

  • Python 3.11+
  • uv package manager (recommended) or pip
  • Access to FortiGate device
  • API token or username/password

🛠️ Installation

1. Clone the Project

git clone https://github.com/alpadalar/fortigate-mcp-server.git
cd fortigate-mcp-server

2. Install Dependencies

# Using uv (recommended) - installs the locked, reproducible dependency set
uv sync --locked

# Or using pip
pip install -e .

3. Configuration

Create your local config from the committed example (config/config.json is gitignored and does not exist on a fresh clone):

cp config/config.example.json config/config.json

Then edit config/config.json:

{
  "server": {
    "allow_writes": false
  },
  "fortigate": {
    "devices": {
      "default": {
        "host": "192.168.1.1",
        "port": 443,
        "username": "admin",
        "password": "your_password",
        "api_token": "your-api-token",
        "vdom": "root",
        "verify_ssl": true,
        "timeout": 30
      }
    }
  },
  "logging": {
    "level": "INFO",
    "file": "./logs/fortigate_mcp.log"
  }
}

🚀 Usage

Start HTTP Server

# Start with script
./start_http_server.sh

# Or manually
uv run python -m src.fortigate_mcp.server_http \
  --host 127.0.0.1 \
  --port 8814 \
  --path /fortigate-mcp \
  --config config/config.json

Use --host 0.0.0.0 only if you need access from other machines on the network AND have auth.require_auth=true configured in config/config.json; otherwise keep 127.0.0.1 — unauthenticated HTTP should never bind wider than loopback.

Run with Docker

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f fortigate-mcp-server

The compose file publishes port 8814 on loopback only (127.0.0.1:8814:8814), so the server is reachable solely from the Docker host itself. To expose it beyond 127.0.0.1, first set auth.require_auth=true in config/config.json, then widen the ports: mapping deliberately — see SECURITY.md.

🔧 MCP Client Integration

FortiGate MCP Server works with any MCP-compatible client. Verified, ready-to-use config examples are provided for Claude Desktop, Claude Code, and Cursor:

Every stdio example in this project launches the server via uv run --directory <path> python -m src.fortigate_mcp.server instead of a bare python -m ... command. This matters because GUI-launched MCP clients (like Claude Desktop) commonly start commands from a directory other than the repo root — the explicit --directory flag makes the invocation working-directory independent, so it keeps working regardless of where the client process happens to start from.

Claude Code (.mcp.json)

Add a project-scope .mcp.json at your repository root (see examples/claude_code_mcp.json for the full file, including the HTTP entry):

{
  "mcpServers": {
    "fortigate-mcp-stdio": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "${CLAUDE_PROJECT_DIR}", "python", "-m", "src.fortigate_mcp.server"],
      "env": {
        "FORTIGATE_MCP_CONFIG": "${CLAUDE_PROJECT_DIR}/config/config.json"
      }
    }
  }
}

Or register the HTTP transport via the Claude Code CLI:

claude mcp add --transport http fortigate-mcp http://127.0.0.1:8814/fortigate-mcp --header "Authorization: Bearer <token>"

--header is only needed when auth.require_auth=true is set in config/config.json.

Claude Desktop

Claude Desktop's native config schema validates stdio servers only. Use examples/claude_desktop_config.stdio.json for the stdio transport (recommended). For the HTTP transport, examples/claude_desktop_config.http.json bridges to this server through the community mcp-remote npm package (npx -y mcp-remote ...) — this package is not vetted or installed by this project; inspect it yourself before running it, since npx fetches and executes third-party code on your behalf.

Cursor

See examples/cursor_mcp_config.json for a working stdio configuration.

📚 API Commands

Device Management

  • list_devices - List registered devices
  • get_device_status - Get device status
  • test_device_connection - Test connection
  • add_device - Add new device
  • remove_device - Remove device
  • discover_vdoms - Discover VDOMs

Firewall Management

  • list_firewall_policies - List firewall rules
  • create_firewall_policy - Create new rule
  • update_firewall_policy - Update rule
  • delete_firewall_policy - Delete rule

Network Management

  • list_address_objects - List address objects
  • create_address_object - Create address object
  • list_service_objects - List service objects
  • create_service_object - Create service object

Virtual IP Management

  • list_virtual_ips - List virtual IPs
  • create_virtual_ip - Create virtual IP
  • update_virtual_ip - Update virtual IP
  • get_virtual_ip_detail - Get virtual IP detail
  • delete_virtual_ip - Delete virtual IP

Routing Management

  • list_static_routes - List static routes
  • create_static_route - Create static route
  • update_static_route - Update static route
  • delete_static_route - Delete static route
  • get_static_route_detail - Get static route detail
  • get_routing_table - Get routing table
  • list_interfaces - List interfaces
  • get_interface_status - Get interface status

System Commands

  • health - Health check
  • test_connection - Connection test
  • get_schema_info - Schema information

🧪 Testing

Run Tests

# One-time setup: test dependencies (pytest, pytest-cov, respx, pyyaml) live in the
# dev/test extras — the plain `uv sync --locked` from the install step does not install them
uv sync --locked --all-extras

# Quick run with coverage disabled (a bare -q only reduces verbosity;
# without --no-cov the coverage gate from pyproject.toml addopts still runs)
uv run pytest -q --no-cov

# Full suite with coverage (--cov-fail-under=67 enforced per pyproject.toml)
uv run pytest

# Run specific test files
uv run pytest tests/test_device_manager.py
uv run pytest tests/test_fortigate_api.py
uv run pytest tests/test_tools.py

# Verbose output
uv run pytest -v

# Detailed error information
uv run pytest --tb=long

Test Categories

  • Unit Tests: Test individual components and functions
  • Coverage: Code coverage reporting with HTML output

Manual Testing

The /health route lives at the app root, is exempt from Bearer-token auth, and works with plain curl:

# Liveness probe
curl http://127.0.0.1:8814/health

The MCP protocol itself cannot be exercised with a bare curl POST: the streamable-HTTP transport requires an initialize handshake, session management, and tools/call framing. Use a real MCP client for protocol-level testing — for example fastmcp.Client:

uv run python - <<'PY'
import asyncio
from fastmcp import Client

async def main():
    # Trailing slash matches the mount convention; the non-slash form 307-redirects
    async with Client("http://127.0.0.1:8814/fortigate-mcp/") as client:
        tools = await client.list_tools()
        print(f"{len(tools)} tools registered")
        result = await client.call_tool("health", {})
        print(result.content[0].text)

asyncio.run(main())
PY

Alternatively, bridge with npx -y mcp-remote http://127.0.0.1:8814/fortigate-mcp or use the MCP Inspector.

📁 Project Structure

fortigate-mcp-server/
├── src/
│   └── fortigate_mcp/
│       ├── __init__.py
│       ├── server.py               # STDIO MCP server
│       ├── server_http.py          # HTTP MCP server
│       ├── config/                 # Configuration management
│       ├── core/                   # Core components
│       ├── tools/                  # MCP tools
│       └── formatting/             # Response formatting
├── config/
│   ├── config.json                # Main configuration (gitignored, created from example)
│   └── config.example.json        # Example configuration
├── examples/
│   ├── claude_desktop_config.stdio.json  # Claude Desktop, stdio transport
│   ├── claude_desktop_config.http.json   # Claude Desktop, HTTP via mcp-remote
│   ├── claude_code_mcp.json               # Claude Code .mcp.json
│   └── cursor_mcp_config.json             # Cursor MCP config
├── logs/                          # Log files
├── tests/                         # Test files
├── docker-compose.yml             # Docker compose
├── Dockerfile                     # Docker image
├── start_server.sh                # STDIO startup script
├── start_http_server.sh           # HTTP startup script
└── README.md                      # This file

🔍 Troubleshooting

Common Issues

  1. Connection Error

    • Ensure FortiGate device is accessible
    • Verify API token or username/password
    • If you see SSL certificate errors, install the FortiGate device's certificate as trusted (or replace it with a CA-signed certificate) — do not disable certificate verification. verify_ssl defaults to true and must stay true; see SECURITY.md for the rationale.

  2. Port Conflict

    • Ensure port 8814 is available
    • Change port using --port parameter

  3. Configuration Error

    • Ensure config.json is properly formatted
    • Check JSON syntax

  4. MCP Client Connection Issue

    • Ensure the server is running
    • Verify the config file path and URL are correct
    • Restart the MCP client (Claude Desktop / Claude Code / Cursor)

Logs

Check logs using:

# HTTP server logs
tail -f logs/fortigate_mcp.log

# Docker logs
docker-compose logs -f fortigate-mcp-server

🔒 Security

Implemented Controls

  1. Write protection (default: read-only)

    • Write and destructive tools are rejected unless explicitly enabled via server.allow_writes: true in config, or the FORTIGATE_MCP_ALLOW_WRITES=1 environment variable

  2. TLS certificate verification (default: on)

    • Config-loaded devices verify TLS certificates by default (verify_ssl: true)

  3. Bearer-token authentication (optional, default: off)

    • Available via auth.require_auth / auth.api_tokens; unauthenticated by default — run only on trusted networks when disabled

  4. Secret redaction

    • API tokens and passwords are stored as SecretStr and are never written to logs

Known Limitations

  • Rate limiting is parsed from config but not enforced — do not rely on it as a working control.
  • Unauthenticated HTTP (the default) should bind to 127.0.0.1 (loopback) only; binding to 0.0.0.0 for wider network access requires enabling Bearer auth (auth.require_auth=true) plus network-level controls (firewall rules, VPN, reverse-proxy allowlists).

See SECURITY.md for the full threat model and known limitations.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

📞 Support

For issues:

  • Use the Issues page
  • Check the documentation
  • Review the logs

Note: This project has been tested with FortiGate devices. Please perform comprehensive testing before using in production.