Palo Alto MCP Server

A Model Context Protocol (MCP) server for managing Palo Alto firewalls. This server provides tools to interact with Palo Alto Networks firewalls through their REST API, following the official PAN-OS REST API v11.2 specification.

Features

• Enhanced Tool Intelligence: Tool descriptions based on official Palo Alto OpenAPI v11.2 specification with intelligent field validation
• System Information: Get system information from Palo Alto firewalls
• Resource Management: List and manage various firewall resources (Objects, Policies, Network, Devices)
• Configuration Management: View and modify configuration nodes using XPath
• Multi-Operations: Perform multi-move and multi-clone operations on configurations
• Comprehensive Error Handling: Detailed, actionable error messages with troubleshooting guidance

Recent Updates

v0.1.3 - Enhanced Tool Descriptions & API Fixes

• Enhanced Tool Descriptions: All tool descriptions now include detailed information from the Palo Alto OpenAPI specification with field requirements, valid values, and proper usage examples
• Security Rules @name Fix: Fixed "Invalid Object: entry attribute name is missing" error when modifying security rules by properly including the @name attribute per OpenAPI specification
• Better LLM Integration: Improved tool descriptions help LLMs understand proper field formats, constraints, and valid values

Installation and Usage

Using npx (Recommended)

You can run the server directly using npx without installing it globally:

npx cokpit-paloalto-mcp-server

Global Installation

npm install -g cokpit-paloalto-mcp-server
paloalto-mcp-server

Local Development

git clone <repository-url>
cd cokpit-paloalto-mcp-server
npm install
npm run build
npm start

Configuration

Environment Variables

Set the following environment variables before running the server:

export PANOS_API_KEY="your-api-key-here"
export PANOS_API_BASE_URL="https://your-firewall.example.com/restapi/v11.2"  # Optional

The default base URL format is https://<your-palo-alto-server-url>/restapi/v11.2 if not specified.

MCP Client Integration

This server works with any MCP-compatible client. Here are configuration examples for popular clients:

Claude Desktop

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "paloalto": {
      "command": "npx",
      "args": ["cokpit-paloalto-mcp-server"],
      "env": {
        "PANOS_API_KEY": "your-api-key-here",
        "PANOS_API_BASE_URL": "https://your-firewall.example.com/restapi/v11.2"
      }
    }
  }
}

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "paloalto": {
      "command": "npx",
      "args": ["cokpit-paloalto-mcp-server"],
      "env": {
        "PANOS_API_KEY": "your-api-key-here",
        "PANOS_API_BASE_URL": "https://your-firewall.example.com/restapi/v11.2"
      }
    }
  }
}

Python LangChain MCP Adapters

For Python applications using LangChain MCP adapters, configure the server as follows:

from langchain_mcp_adapters import create_mcp_connection

# Basic configuration
mcp_config = {
    "command": "npx",
    "args": ["cokpit-paloalto-mcp-server"],
    "transport": "stdio",
    "env": {
        "PANOS_API_KEY": "your-api-key-here",
        "PANOS_API_BASE_URL": "https://your-firewall.example.com/restapi/v11.2"
    }
}

# Create MCP connection
connection = create_mcp_connection(mcp_config)

# Alternative: Using local installation
mcp_config_local = {
    "command": "node",
    "args": ["/path/to/cokpit-paloalto-mcp-server/build/index.js"],
    "transport": "stdio",
    "env": {
        "PANOS_API_KEY": "your-api-key-here",
        "PANOS_API_BASE_URL": "https://your-firewall.example.com/restapi/v11.2"
    }
}

Python with Specific Environment Setup

import os
from langchain_mcp_adapters import MCPAdapter

# Set environment variables
os.environ["PANOS_API_KEY"] = "your-api-key-here"
os.environ["PANOS_API_BASE_URL"] = "https://your-firewall.example.com/restapi/v11.2"

# Configure MCP server
mcp_adapter = MCPAdapter(
    command="npx",
    args=["cokpit-paloalto-mcp-server"],
    transport="stdio"
)

# Use the adapter
async def manage_firewall():
    # List security rules
    security_rules = await mcp_adapter.call_tool("list_resources", {
        "category": "POLICIES",
        "resource_type": "SecurityRules",
        "location": "vsys",
        "vsys": "vsys1"
    })
    
    # Create a security rule
    new_rule = await mcp_adapter.call_tool("create_resource", {
        "category": "POLICIES",
        "resource_type": "SecurityRules",
        "name": "allow-web-traffic",
        "location": "vsys",
        "vsys": "vsys1",
        "data": {
            "from": {"member": ["trust"]},
            "to": {"member": ["untrust"]},
            "source": {"member": ["any"]},
            "destination": {"member": ["any"]},
            "service": {"member": ["service-http", "service-https"]},
            "application": {"member": ["any"]},
            "action": "allow",
            "description": "Allow web traffic from trust to untrust zone"
        }
    })

Generic MCP Client

For any MCP client that supports external servers:

Command: npx cokpit-paloalto-mcp-server Environment Variables:

• PANOS_API_KEY: Your Palo Alto API key
• PANOS_API_BASE_URL: Your firewall's API base URL (optional)

Local Development Configuration

If you're developing locally or want to use a local version:

{
  "mcpServers": {
    "paloalto": {
      "command": "node",
      "args": ["/path/to/cokpit-paloalto-mcp-server/build/index.js"],
      "env": {
        "PANOS_API_KEY": "your-api-key-here",
        "PANOS_API_BASE_URL": "https://your-firewall.example.com/restapi/v11.2"
      }
    }
  }
}

Available Tools

All tools are enhanced with detailed information from the Palo Alto OpenAPI v11.2 specification, including field requirements, valid values, and proper usage examples.

1. get_system_info

Get system information from the Palo Alto firewall, including virtual systems configuration and device status.

Parameters: None

2. list_resources

List resources from a specific category with optional filtering. This tool retrieves configuration objects from PAN-OS REST API v11.2.

Parameters:

• category (required): One of OBJECTS, POLICIES, NETWORK, DEVICES
• resource_type (required): Specific resource type within the category (must match PAN-OS API resource names exactly)
• filter (optional): Filter for resources by name pattern (uses substring matching)
• location (required): Location type per OpenAPI spec - predefined, shared, vsys, panorama-pushed
• vsys (optional): Virtual system name (required when location="vsys" for non-NETWORK resources)

Resource Categories:

• POLICIES (Security, NAT, QoS rules): SecurityRules, NATRules, QoSRules, PolicyBasedForwardingRules, DecryptionRules, etc.
• OBJECTS (Address, Service, Application objects): Addresses, AddressGroups, Services, ServiceGroups, Tags, Applications, etc.
• NETWORK (Interfaces, Zones, VPNs): EthernetInterfaces, VLANInterfaces, Zones, VirtualRouters, IPSecTunnels (ONLY supports panorama-pushed location)
• DEVICES (System configuration): VirtualSystems, SNMPTrapServerProfiles, SyslogServerProfiles, etc.

⚠️ IMPORTANT: Exact Parameter Values Required

Example Usage:

// ✅ CORRECT: Get all security rules (MOST COMMON USE CASE)
await useMcpTool("list_resources", {
  category: "POLICIES",
  resource_type: "SecurityRules",  // ✅ Use "SecurityRules" (not "security")
  location: "vsys",                // ✅ Required parameter  
  vsys: "vsys1"                   // ✅ Required when location="vsys"
});

// ✅ CORRECT: Get predefined services (system built-in services like HTTP, HTTPS)
await useMcpTool("list_resources", {
  category: "OBJECTS",
  resource_type: "Services",
  location: "predefined"          // ✅ No vsys needed for predefined
});

// ✅ CORRECT: Get network interfaces (NETWORK resources require panorama-pushed)
await useMcpTool("list_resources", {
  category: "NETWORK",
  resource_type: "EthernetInterfaces",
  location: "panorama-pushed"     // ✅ NETWORK resources ONLY support this location
});

3. create_resource

Create a new resource in PAN-OS. This tool follows the OpenAPI v11.2 specification and automatically includes the required @name attribute in the entry.

Parameters:

• category (required): Resource category (OBJECTS, POLICIES, NETWORK, DEVICES)
• resource_type (required): Specific resource type to create (must match PAN-OS API names exactly)
• name (required): Name of the resource (max 63 chars, alphanumeric plus ._- per OpenAPI spec)
• location (required): shared, vsys, or panorama-pushed (cannot create in predefined)
• vsys (required when location="vsys"): Virtual system name
• data (required): Resource configuration data as JSON object

Key Data Structure Requirements (per OpenAPI specification):

• Security Rules (all fields required): from, to, source, destination, service, application, action
  • Valid actions: "allow", "deny", "drop", "reset-client", "reset-server", "reset-both"
  • Use exact service names: "service-http", "service-https", "application-default", "any"
• Address Objects: {"ip-netmask": "192.168.1.0/24"} OR {"fqdn": "example.com"} OR {"ip-range": "192.168.1.1-192.168.1.10"}
• Service Objects: {"protocol": {"tcp": {"port": "8080"}}}
• Arrays must use {"member": [...]} format per PAN-OS API

4. modify_resource

Modify an existing resource in PAN-OS. This tool automatically retrieves existing configuration, merges changes, and includes the required @name attribute. Only specify fields that need to be changed.

Parameters:

• category (required): Resource category where the resource exists
• resource_type (required): Specific resource type to modify (must match existing exactly)
• name (required): Name of the existing resource to modify
• location (required): Location where the resource exists (cannot modify predefined resources)
• vsys (required when location="vsys"): Virtual system name
• data (required): Updated configuration data (only specify fields to change)

5. delete_resource

Delete an existing resource from PAN-OS. This permanently removes the configuration object.

Parameters:

• category (required): Resource category to delete from
• resource_type (required): Specific resource type to delete
• name (required): Name of the existing resource to delete
• location (required): Location where the resource exists (cannot delete predefined resources)
• vsys (required when location="vsys"): Virtual system name

6. view_config_node_values

View configuration node values for specific XPath on the Palo Alto firewall. This provides direct access to the PAN-OS configuration tree structure.

Parameters:

• xpath (required): XPath to the configuration node

7. multi_move_clone_configuration

Multi-Move or Multi-Clone configuration elements in the Palo Alto firewall. Useful for bulk operations.

Parameters:

• config_paths (required): Array of configuration paths to move or clone
• new_location (required): Destination location for the configurations
• action (required): Either move or clone

API Key Setup

To obtain a Palo Alto API key:

1. Log into your Palo Alto firewall web interface
2. Go to Device > Setup > Management > Authentication Settings
3. Click Generate to create a new API key
4. Copy the generated key and use it as the PANOS_API_KEY environment variable

Error Handling

The server includes comprehensive error handling with detailed, actionable error messages that help diagnose and fix issues:

Enhanced Error Messages

Instead of generic "unknown error" messages, the server now provides:

• Specific error categories (Connection Refused, DNS Resolution Failed, Authentication Failed, etc.)
• Root cause analysis with detailed explanations
• Step-by-step solutions for common problems
• Troubleshooting checklists for systematic diagnosis
• HTTP status code interpretation with context

Common Error Scenarios Handled

• Missing API keys - Clear instructions on how to obtain and set API keys
• Invalid API requests - Detailed parameter validation with suggestions
• Network connectivity issues - Connection troubleshooting steps
• Authentication failures - API key validation and permission checks
• Authorization problems - Role and permission guidance
• Firewall unavailability - Service status and retry recommendations
• SSL/TLS certificate issues - HTTPS configuration guidance

Example Error Output

When an error occurs, you'll see detailed messages like:

Palo Alto API error during modify_resource:
- HTTP 400 Bad Request
- REQUEST: PUT /Policies/SecurityRules
- SERVER RESPONSE: {
  "code": 3,
  "message": "Invalid Object",
  "details": [
    {
      "@type": "CauseInfo",
      "causes": [
        {
          "code": 12,
          "module": "panui_mgmt",
          "description": "Invalid Object: entry attribute name is missing."
        }
      ]
    }
  ]
}

- TROUBLESHOOTING CHECKLIST:
  1. Verify PANOS_API_KEY is set and valid
  2. Check PANOS_API_BASE_URL format: https://firewall-ip/restapi/v11.2
  3. Ensure firewall is accessible from your network
  4. Confirm API is enabled on the firewall
  5. Check if SSL certificate issues (if using HTTPS)

This detailed error information enables LLMs to provide specific, actionable suggestions for resolving issues.

Requirements

• Node.js 18.0.0 or later
• Valid Palo Alto firewall API access
• API key with appropriate permissions

Development

Building from Source

npm install
npm run build

Running Tests

npm test

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

1. Check the existing issues on GitHub
2. Create a new issue with detailed information about your problem
3. Include your environment details and error messages

Palo Alto OpenAPI Spec

The tool descriptions and validations are based on the official Palo Alto OpenAPI specification. You can reference the spec at: https://gist.githubusercontent.com/venkatb-zelar/ab50f60f031e0c64ad2a6ca50483077e/raw/622b0046937665d59511d96a4b3797920bd01070/paloalto-openapi.yaml