MCP Fortios Server

FortiOS MCP服务器

使用FastMCP构建的用于FortiOS集成的容器化模型上下文协议（MCP）服务器。

🚀 快速开始

先决条件

• Docker和Docker Compose
• Python 3.13+（用于本地开发）
• uv包管理器

使用Docker运行

1. 构建并启动服务器：

   docker-compose up --build -d

1. 检查服务器状态：

   docker logs mcp-fortios-server

1. 测试服务器：

   # The server will be available at http://localhost:8000/mcp
   curl -X POST http://localhost:8000/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: text/event-stream" \
     -d '{"jsonrpc":"2.0","id":"test","method":"tools/list"}'

可用工具

服务器通过MCP提供全面的FortiOS管理工具：

🔥 防火墙策略工具

• create_firewall_policy -创建具有完整配置的防火墙策略
• get_firewall_policies -检索所有或特定的防火墙策略

🏠 地址对象工具

• create_address -创建地址对象（ipmask、iprange、fqdn类型）
• get_addresses -检索所有或特定的地址对象
• delete_address -删除地址对象

👥 地址组工具

• create_address_group -创建包含现有地址对象的组
• get_address_groups -检索所有或特定的地址组
• delete_address_group -删除地址组

🌐 VIP（虚拟IP）工具

• create_vip -为端口转发/NAT创建VIP对象
• get_vips -检索所有或特定VIP对象

🔧 实用工具

• ping_fortigate -测试FortiOS设备的连接性和响应性

MCP协议

此服务器使用以下方式通过HTTP实现模型上下文协议（MCP）：

• 端点： http://localhost:8000/mcp
• 协议： 基于HTTP的JSON-RPC 2.0
• 运输： 服务器发送事件（SSE）
• 内容类型： application/json
• 接受： text/event-stream

发展

地方发展设置

1. 安装依赖项：

   uv add starlette fastmcp uvicorn

1. 在本地运行：

   uvicorn app.server:app --host 0.0.0.0 --port 8000 --reload

Docker命令

# Build the image
docker-compose build

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Rebuild and restart
docker-compose up --build -d

项目结构

mcp_fortios/
├── app/                     # Core application
│   ├── __init__.py         # Python package init
│   ├── server.py           # Main MCP server with all FortiOS tools
│   ├── fortios_client.py   # FortiOS API client
│   └── tools.py            # FortiOS tools implementation
├── tests/                   # Test suite
│   ├── __init__.py         # Test package init
│   ├── test_basic.py       # Unit tests
│   └── test_integration.py # Integration tests
├── examples/                # Usage examples and utilities
│   ├── __init__.py         # Examples package init
│   ├── usage_examples.py   # Comprehensive usage examples
│   └── mcp_client.py       # Advanced MCP client with session management
├── .github/workflows/       # CI/CD pipeline
│   └── ci.yml              # GitHub Actions workflow
├── Dockerfile              # Container configuration
├── docker-compose.yml      # Docker Compose setup
├── k8s-deployment.yaml     # Kubernetes deployment
├── health_check.py         # Server health check script
├── pyproject.toml          # Python dependencies and project metadata
├── uv.lock                 # Dependency lock file
├── LICENSE                 # MIT License
├── CONTRIBUTING.md         # Contributing guidelines
├── SECURITY.md             # Security policy
└── README.md               # This file

整合

要将此MCP服务器与您的应用程序集成：

1. MCP客户端： 使用任何兼容MCP的客户端
2. API终结点： http://localhost:8000/mcp
3. 身份验证： 目前没有（根据需要添加）
4. 协议： 基于HTTP的标准MCP

版本控制和发布

该项目如下 语义化版本 使用格式 v1.0.1.

发布

1. 使用发布脚本 （推荐）：

   # Increment patch version (1.0.0 → 1.0.1)
   ./scripts/release.sh patch

   # Increment minor version (1.0.1 → 1.1.0)
   ./scripts/release.sh minor

   # Increment major version (1.1.0 → 2.0.0)
   ./scripts/release.sh major

   # Set specific version
   ./scripts/release.sh v1.2.3

1. 人工处理:

   # Update version in pyproject.toml
   # Commit the change
   git add pyproject.toml
   git commit -m "chore: bump version to 1.0.1"

   # Create and push tag
   git tag -a v1.0.1 -m "Release v1.0.1"
   git push origin main
   git push origin v1.0.1

Docker镜像标签

Docker镜像是 仅在创建版本标记时构建和推送.CI/CD管道创建：

• your-username/mcp-fortios-server:v1.0.1 （精确版本标签）
• your-username/mcp-fortios-server:latest （随每个新版本更新）

没有图像是建立在定期推送到main上的基础上的 -仅在版本标签上。

日志

容器日志可通过以下方式获得：

docker logs mcp-fortios-server

日志包括：

• 服务器启动和关闭
• 会话管理
• 工具请求和响应
• 错误处理

工具示例

创建地址对象

# Create subnet address
create_address(
    name="WebServers",
    address_type="ipmask", 
    subnet="192.168.100.0 255.255.255.0",
    comment="Web server subnet",
    fortigate_url="https://192.168.1.99",
    fortigate_token="your-token",
    fortigate_vdom="root"
)

# Create FQDN address  
create_address(
    name="GoogleDNS",
    address_type="fqdn",
    fqdn="dns.google.com",
    fortigate_url="https://192.168.1.99",
    fortigate_token="your-token"
)

创建防火墙策略

create_firewall_policy(
    name="Allow_Web_Access",
    srcintf=["internal"],
    dstintf=["wan1"], 
    srcaddr=["WebServers"],
    dstaddr=["all"],
    service=["HTTP", "HTTPS"],
    action="accept",
    fortigate_url="https://192.168.1.99",
    fortigate_token="your-token"
)

测试

1. 服务器健康检查：

   python health_check.py

1. 健康检查：

   python health_check.py

1. 完整的工具示例：

   python examples/usage_examples.py

1. MCP协议测试：

   python examples/mcp_client.py

1. 运行测试套件：

   uv run pytest tests/ -v

故障排除

1. 端口已在使用中：

   # Change port in docker-compose.yml
   ports:
     - "8001:8000"  # Use port 8001 instead

1. 容器未启动：

   # Check logs
   docker-compose logs mcp-fortios-server

   # Rebuild from scratch
   docker-compose down
   docker-compose build --no-cache
   docker-compose up

1. 连接被拒绝：

- 确保容器正在运行： docker-compose ps - 检查是否露出正确的端口 - 验证没有防火墙阻止端口

1. FortiOS API错误：

- 验证FortiGate URL是否可访问 - 检查API令牌是否有效并具有所需的权限 - 确保VDOM名称正确 - 查看FortiGate API文档以了解具体的错误代码

生产使用

1. 替换测试凭据 在具有真实FortiGate细节的示例中
2. 安全的API令牌 使用环境变量或机密
3. 启用SSL验证 用于生产FortiGate连接
4. 添加错误处理 并重试网络问题的逻辑
5. 实施日志记录 用于审计跟踪
6. 设置监控 用于服务器运行状况和API使用