BIG-IP MCP Server

# BIG-IP MCP Server A Model Context Protocol (MCP) server for managing F5 BIG-IP devices. Built with FastMCP 2.0, this server provides tools to authenticate to BIG-IP load balancers and query virtual server configurations. ## Features - **Configuration-Based Credentials** - Store BIG-IP credentials securely in a JSON config file - **Multi-Device Support** - Manage multiple BIG-IP devices from a single server - **Token Caching** - Automatically caches authentication tokens and reuses until expiry - **Virtual Server Management** - List all virtual servers with status and configuration - **AS3 Management** - Check, install, and upgrade F5 Application Services 3 Extension - **SSL Flexibility** - Support for self-signed certificates (common in lab environments) - **Async/Await** - Non-blocking I/O for responsive performance ## Quick Start 1. **Install dependencies** (see Installation section below) 2. **Create configuration file:** ```bash cp bigip_config.example.json bigip_config.json ``` 3. **Edit `bigip_config.json`** with your BIG-IP device details 4. **Restart Claude Desktop** to load the server 5. **Use the tools:** Ask Claude to "list BIG-IP devices" or "list virtual servers on [device-name]" ## Installation ### Step 1: Create a Virtual Environment #### Using venv (recommended for standard Python) ```bash # Create virtual environment python -m venv venv # Activate on macOS/Linux source venv/bin/activate # Activate on Windows venv\Scripts\activate ``` #### Using uv (recommended for modern Python projects) ```bash # Create virtual environment with uv uv venv # Activate on macOS/Linux source .venv/bin/activate # Activate on Windows .venv\Scripts\activate ``` ### Step 2: Install Dependencies With virtual environment activated: #### Using uv ```bash uv pip install -r requirements.txt ``` #### Using pip ```bash pip install -r requirements.txt ``` ### Step 3: Verification Confirm FastMCP is installed: ```bash fastmcp version ``` **Note:** Always activate your virtual environment before running the server or installing packages. ## Running the Server **Important:** Make sure your virtual environment is activated before running the server. ### Method 1: Direct execution (stdio transport) ```bash # Ensure venv is activated first source venv/bin/activate # or source .venv/bin/activate for uv python server.py ``` ### Method 2: FastMCP CLI Run with stdio transport (default for MCP): ```bash # Ensure venv is activated first source venv/bin/activate fastmcp run server.py:mcp ``` Run with HTTP transport: ```bash fastmcp run server.py:mcp --transport http --port 8000 ``` ## Configuration ### Creating Your Configuration File 1. Copy the example configuration: ```bash cp bigip_config.example.json bigip_config.json ``` 2. Edit `bigip_config.json` with your BIG-IP devices: ```json { "devices": { "prod-lb-01": { "ip_address": "10.1.1.10", "username": "admin", "password": "your-password", "verify_ssl": false, "description": "Production load balancer" }, "lab-bigip": { "ip_address": "192.168.1.100", "username": "admin", "password": "admin", "verify_ssl": false, "description": "Lab environment" } } } ``` 3. **Security Note:** `bigip_config.json` is automatically excluded from git (.gitignore) See [CONFIGURATION.md](CONFIGURATION.md) for detailed configuration guide. ## Available Tools ### `list_bigip_devices` List all configured BIG-IP devices from the configuration file. **Usage:** ``` Show me the configured BIG-IP devices ``` **Returns:** List of device names, IP addresses, and descriptions ### `list_virtual_servers` List all virtual servers on a specific BIG-IP device. **Parameters:** - `device_name` - Name of the device from config file (e.g., 'prod-lb-01') **Usage:** ``` List virtual servers on prod-lb-01 ``` **Returns:** Formatted list of virtual servers with status, destination, and configuration details **Features:** - Reads credentials from configuration file (no passwords in chat!) - Automatically authenticates and caches token - Token reused for 19 minutes before re-authentication ### `manage_as3` Check, install, or upgrade F5 AS3 (Application Services 3 Extension) on BIG-IP devices. **Parameters:** - `device_name` - Name of the device from config file (e.g., 'prod-lb-01') - `action` - Action to perform: "check" (default), "install", or "upgrade" - `auto_install` - Set to True to proceed with installation/upgrade (default: False) **Usage:** ``` Check AS3 status on prod-lb-01 Install AS3 on lab-bigip Upgrade AS3 on prod-lb-01 ``` **Returns:** AS3 version information and installation/upgrade results **Features:** - Automatically fetches latest AS3 version from GitHub - Downloads and uploads RPM to BIG-IP - Polls installation task until completion - Verifies installation after completion - Supports version comparison and upgrade recommendations - Two-step confirmation with `auto_install` parameter prevents accidental installations **Requirements:** - AS3 installation requires admin account (not just administrator role) - Network access to GitHub for downloading RPM packages - BIG-IP 14.1+ recommended for AS3 3.50+ ### Resources - **`config://server`** - Server configuration and capabilities ### Prompts - **`help_prompt()`** - Overview of server capabilities and usage ## Usage with Claude Desktop Add this server to your Claude Desktop configuration: ### macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` ### Windows: `%APPDATA%\Claude\claude_desktop_config.json` **Recommended: Using the wrapper script (avoids permission issues)** ```json { "mcpServers": { "bigip": { "command": "/Users/a.ganti/Documents/code/mcp-servers/big-ip/run_server.sh" } } } ``` The wrapper script automatically handles virtual environment activation and works around macOS permission restrictions. **Alternative options (if you have permission issues):** <details> <summary>Option 1: Direct Python from virtual environment</summary> ```json { "mcpServers": { "bigip": { "command": "/Users/a.ganti/Documents/code/mcp-servers/big-ip/venv/bin/python", "args": ["/Users/a.ganti/Documents/code/mcp-servers/big-ip/server.py"] } } } ``` </details> <details> <summary>Option 2: FastMCP CLI from virtual environment</summary> ```json { "mcpServers": { "bigip": { "command": "/Users/a.ganti/Documents/code/mcp-servers/big-ip/venv/bin/fastmcp", "args": ["run", "/Users/a.ganti/Documents/code/mcp-servers/big-ip/server.py:mcp"] } } } ``` </details> **Note:** Update the paths above to match your actual installation directory. If using `uv`, change `venv` to `.venv` in the paths. After updating the config, restart Claude Desktop to load the server. ## Using the BIG-IP Tools ### Example Interactions **List Available Devices:** ``` Show me the configured BIG-IP devices ``` **List Virtual Servers:** ``` List virtual servers on prod-lb-01 ``` Or more naturally: ``` Can you show me the virtual servers on the lab-bigip device? ``` **Check Multiple Devices:** ``` List virtual servers on prod-lb-01 and then on prod-lb-02 ``` **Check AS3 Status:** ``` Check AS3 status on prod-lb-01 ``` **Install AS3:** ``` Install AS3 on lab-bigip ``` **Upgrade AS3:** ``` Upgrade AS3 on prod-lb-01 if a newer version is available ``` ### Workflow 1. **First time:** Create and configure `bigip_config.json` with your devices 2. **Check devices:** Ask Claude to list available BIG-IP devices 3. **Query virtual servers:** Specify the device name from your config 4. **Credentials:** Read automatically from config file (no passwords in chat!) 5. **Subsequent requests:** Authentication tokens cached for efficiency ## BIG-IP Requirements ### Network Access - The machine running this MCP server must have network access to the BIG-IP management interface (typically port 443/HTTPS) - Ensure firewall rules allow outbound HTTPS connections to your BIG-IP device ### BIG-IP Configuration - BIG-IP must have iControl REST API enabled (enabled by default) - User account must have appropriate permissions to: - Authenticate via iControl REST - Read virtual server configurations (typically requires at least "Guest" role) ### Supported Versions - BIG-IP version 12.0 or higher (for token-based authentication) - Tested with BIG-IP 13.x, 14.x, 15.x, 16.x, 17.x ### SSL Certificates - For production BIG-IP devices with valid SSL certificates, set `verify_ssl: true` - For lab/dev environments with self-signed certificates, use `verify_ssl: false` (default) ## Security Considerations ### Credential Handling - **Never hardcoded** - Credentials are requested interactively via MCP's elicitation feature - **Session-scoped caching** - Credentials are cached only for the current MCP session - **Token-based auth** - Password is only sent during initial authentication; subsequent requests use tokens - **Automatic expiry** - Tokens expire after 19 minutes and are automatically refreshed ### Best Practices 1. Use dedicated service accounts with read-only permissions when possible 2. Enable SSL verification (`verify_ssl: true`) for production environments 3. Use the `clear_bigip_credentials` tool when switching between BIG-IP devices 4. Ensure Claude Desktop has appropriate file permissions (see Troubleshooting) ## Troubleshooting ### Permission Errors with Virtual Environment If you see errors like `PermissionError: [Errno 1] Operation not permitted: '/path/to/venv/pyvenv.cfg'`: 1. **Use the wrapper script** (recommended): ```json { "mcpServers": { "bigip": { "command": "/Users/a.ganti/Documents/code/mcp-servers/big-ip/run_server.sh" } } } ``` 2. **Grant Claude Desktop Full Disk Access**: - Open System Settings → Privacy & Security → Full Disk Access - Add Claude and enable access - Restart Claude Desktop 3. **Or recreate the virtual environment**: ```bash rm -rf venv python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` ### BIG-IP Connection Issues **"Failed to connect to BIG-IP"** - Verify network connectivity: `ping <bigip-ip>` - Verify HTTPS access: `curl -k https://<bigip-ip>/mgmt/shared/authn/login` - Check firewall rules allow outbound HTTPS (port 443) **"Authentication failed: 401"** - Verify username and password are correct - Check user account is enabled in BIG-IP - Verify user has API access permissions **"SSL verification failed"** - For self-signed certificates, set `verify_ssl: false` when prompted - For production, ensure BIG-IP has valid SSL certificate **"Failed to retrieve virtual servers: 403"** - User account lacks permissions to read LTM configuration - Requires at least "Guest" role or custom role with `ltm` read permissions ### Server Not Connecting Check the Claude Desktop logs for errors. The wrapper script provides better error handling and environment isolation. ## Development ### Adding More Tools To add additional BIG-IP management capabilities: 1. Create a new async function using the `@mcp.tool` decorator 2. Use `ctx: Context` parameter for logging and elicitation 3. Reuse cached credentials from context state 4. Follow the pattern in `list_virtual_servers` for authentication Example: ```python @mcp.tool async def list_pools(ctx: Context) -> str: """List all load balancing pools""" # Get cached credentials credentials = ctx.get_state("bigip_credentials") token = ctx.get_state("bigip_token") # Your implementation here ... ``` ### Extending Functionality Additional F5 BIG-IP operations that could be added: - List pool members and their status - Query pool statistics - List iRules - Get SSL certificate information - Query virtual server statistics - List nodes and their availability ## Documentation - **FastMCP**: https://gofastmcp.com - **MCP Protocol**: https://modelcontextprotocol.io - **F5 BIG-IP iControl REST API**: https://clouddocs.f5.com/api/icontrol-rest/ - **F5 LTM Virtual Server API**: https://clouddocs.f5.com/api/icontrol-rest/APIRef_tm_ltm_virtual.html ## License This project is provided as-is for managing F5 BIG-IP devices via the MCP protocol.