Zscaler MCP

PyPI version PyPI - Python Version License Zscaler Community Documentation codecov GitHub commit activity Automation Hub

zscaler-mcp-server is a Model Context Protocol (MCP) server that connects AI agents with the Zscaler Zero Trust Exchange platform.

Important

Public Preview

This project is currently in public preview and under active development. Features and functionality may change before the stable 1.0 release. While we encourage exploration and testing, please avoid production deployments. We welcome your feedback through GitHub Issues to help shape the final release.

Support Disclaimer

Warning

Disclaimer: Please refer to our General Support Statement before proceeding with the use of this provider. You can also refer to our troubleshooting guide for guidance on typical problems.

Table of Contents

Overview

The Zscaler Integrations MCP Server brings context to your agents. Try prompts like:

  • “List my ZPA Application segments”

  • “List my ZPA Segment Groups”

  • “List my ZIA Rule Labels”

Supported Services

The server exposes 300+ tools across nine Zscaler services. Tools follow a strict {service}_{verb}_{resource} naming convention (e.g. zia_list_locations, zpa_create_application_segment, zdx_get_application).

Service

Tool modules

What it covers

ZIA

41

Cloud Firewall, URL Filtering, SSL Inspection, Web DLP, File Type Control, Sandbox Rules, Cloud App Control, ATP Policy (incl. malware + advanced settings), Locations, Users, Devices, Authentication Settings, Time Intervals, Shadow IT, Admin & activation.

ZPA

29

Application Segments (standard / BA / PRA), Access / Forwarding / Timeout / Isolation policies, App Connector Groups, Server Groups, Segment Groups, Service Edge Groups, Provisioning Keys, PRA Portals + Credentials, App Protection, Posture, Trusted Networks, IdP / SAML / SCIM, Microtenants.

ZDX

20

Applications, Application Scores & Metrics, Users, Devices, Locations, Departments, Geolocations, Alerts (active + historical), Deep Traces, Software Inventory, CloudPath probes, Web probes.

ZCC

4

Device enrollment, Trusted Networks, Forwarding Profiles, Web App Service.

ZTW

10

Workload Segmentation: IP Groups, Network Services, Cloud Accounts, Admin Roles.

ZIdentity

2

Users, Groups.

EASM

3

External Attack Surface: Organizations, Findings, Scan Evidence, Lookalike Domains.

Z-Insights

7

Analytics across Web Traffic, Threats, Cyber Incidents, Firewall, CASB, Shadow IT, IoT.

ZMS

9

Microsegmentation: Agents, Resources, Resource Groups, Policy Rules, App Zones, App Catalog, Tags, Nonces.

For the full alphabetical tool index, see Zscaler Integrations MCP Server Tools. For tool grouping (load only the slice an agent needs), see Toolsets.

Note

Tool catalogs in Zscaler Integrations MCP Server Tools are organized one tool per page. The toolsets system lets you load a curated subset at startup (e.g. --toolsets zia_url_filtering) instead of every tool from every service.

Skills, Toolsets, Security

Three top-level features expand what the server can do beyond raw tool calls:

  • Toolsets — 52 named groupings (e.g. zia_url_filtering, zpa_app_segments) that scope which tools are loaded. Use --toolsets to pick at startup or zscaler_enable_toolset to enable at runtime.

  • Skills — 42 guided multi-step workflows that an AI agent auto-activates when a user’s request matches the skill’s description (e.g. “block ChatGPT for everyone” → zia-create-cloud-app-control-rule).

  • Security — write operations + HMAC confirmations, MCP client authentication, TLS / host / source-IP hardening, output sanitization, and process lifecycle management (reload / restart / status / stop).

Installation & Setup

Prerequisites

  • Python 3.11 or higher

  • uv or pip

  • Zscaler API credentials (see below)

Environment Configuration

Copy the example environment file and configure your credentials:

cp .env.example .env

Then edit .env with your Zscaler API credentials:

Required Configuration (OneAPI):

  • ZSCALER_CLIENT_ID: Your Zscaler OAuth client ID

  • ZSCALER_CLIENT_SECRET: Your Zscaler OAuth client secret

  • ZSCALER_CUSTOMER_ID: Your Zscaler customer ID

  • ZSCALER_VANITY_DOMAIN: Your Zscaler vanity domain

Optional Configuration:

  • ZSCALER_CLOUD: (Optional) Zscaler cloud environment (e.g., beta) - Required when interacting with Beta Tenant ONLY.

  • ZSCALER_PRIVATE_KEY: (Optional) PEM-encoded private key for JWT-based OneAPI auth, used in place of ZSCALER_CLIENT_SECRET.

  • ZSCALER_MCP_SERVICES: Comma-separated list of services to enable (default: all services)

  • ZSCALER_MCP_TRANSPORT: Transport method - stdio, sse, or streamable-http (default: stdio)

  • ZSCALER_MCP_DEBUG: Enable debug logging - true or false (default: false)

  • ZSCALER_MCP_HOST: Host for HTTP transports (default: 127.0.0.1)

  • ZSCALER_MCP_PORT: Port for HTTP transports (default: 8000)

Alternatively, you can set these as environment variables instead of using a `.env` file.

Important

Ensure your API client has the necessary permissions for the services you plan to use. You can always update permissions later in the Zscaler console.

Installation

Install from source using uv (development)

uv pip install -e .

Install from source using pip

pip install -e .

Install using make (convenience)

make install-dev

Tip

If zscaler-mcp-server isn’t found, update your shell PATH.

For installation via code editors/assistants, see the Using the MCP Server with Agents section below.

Usage

Command Line

Run the server with default settings (stdio transport):

zscaler-mcp

Run with SSE transport:

zscaler-mcp --transport sse

Run with streamable-http transport:

zscaler-mcp --transport streamable-http

Run with streamable-http transport on custom port:

zscaler-mcp --transport streamable-http --host 0.0.0.0 --port 8080

Service Configuration

The Zscaler Integrations MCP Server supports multiple ways to specify which services to enable:

1. Command Line Arguments (highest priority)

Specify services using comma-separated lists:

# Enable specific services
zscaler-mcp --services zia,zpa,zdx

# Enable only one service
zscaler-mcp --services zia

2. Environment Variable (fallback)

Set the ZSCALER_MCP_SERVICES environment variable:

# Export environment variable
export ZSCALER_MCP_SERVICES=zia,zpa,zdx
zscaler-mcp

# Or set inline
ZSCALER_MCP_SERVICES=zia,zpa,zdx zscaler-mcp

3. Default Behavior (all services)

If no services are specified via command line or environment variable, all available services are enabled by default.

Service Priority Order:

  1. Command line --services argument (overrides all)

  2. ZSCALER_MCP_SERVICES environment variable (fallback)

  3. All services (default when none specified)

Additional Command Line Options

For all available options:

zscaler-mcp --help

Supported Agents

See Integrations for IDE plugins, Registries and Marketplaces for the published registry / marketplace listings, and Claude Desktop Extension for the Claude Desktop extension walkthrough.

Zscaler API Credentials & Authentication

The Zscaler Integrations MCP Server uses OneAPI authentication exclusively. A single set of ZIdentity credentials authenticates the server to every Zscaler product.

Zscaler OneAPI Authentication

Before using the Zscaler Integrations MCP Server, you need to create API credentials in your Zidentity console. The Zscaler Integrations MCP Server supports Zscaler’s OneAPI authentication via OAuth2.0 as the default and preferred method.

Create a .env file in your project root with the following:

ZSCALER_CLIENT_ID=your_client_id
ZSCALER_CLIENT_SECRET=your_client_secret
ZSCALER_CUSTOMER_ID=your_customer_id
ZSCALER_VANITY_DOMAIN=your_vanity_domain
ZSCALER_CLOUD=beta

Warning

Do not commit .env to source control. Add it to your .gitignore.

You can provide credentials via the ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN, ZSCALER_CLOUD environment variables, representing your Zidentity OneAPI credentials clientId, clientSecret, vanityDomain and cloud respectively.

OneAPI Authentication Parameters

Argument

Description

Environment variable

clientId

Zscaler API Client ID, used with clientSecret or PrivateKey OAuth auth mode.

ZSCALER_CLIENT_ID

clientSecret

A string that contains the password for the API admin.

ZSCALER_CLIENT_SECRET

vanityDomain

Refers to the domain name used by your organization i.e acme

ZSCALER_VANITY_DOMAIN

cloud

The Zidentity cloud to authenticate to i.e beta

ZSCALER_CLOUD

Container Usage

The Zscaler Integrations MCP Server is available as a pre-built container image for easy deployment:

Building Locally (Development)

For development or customization purposes, you can build the image locally:

# Build the Docker image
docker build -t zscaler-mcp-server .

# Run the locally built image
docker run --rm -e ZSCALER_CLIENT_ID=your_client_id -e ZSCALER_CLIENT_SECRET=your_secret \
  -e ZSCALER_CUSTOMER_ID=your_customer_id -e ZSCALER_VANITY_DOMAIN=your_vanity_domain zscaler-mcp-server

Note

When using HTTP transports in Docker, always set --host 0.0.0.0 to allow external connections to the container.

Editor/Assistant Integration

You can integrate the Zscaler Integrations MCP Server with your editor or AI assistant. Here are configuration examples for popular MCP clients:

With Service Selection

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "uvx",
      "args": [
        "--env-file", "/path/to/.env",
        "zscaler-mcp-server",
        "--services", "zia,zpa,zdx"
      ]
    }
  }
}

Using Individual Environment Variables

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "uvx",
      "args": ["zscaler-mcp-server"],
      "env": {
        "ZSCALER_CLIENT_ID": "your-client-id",
        "ZSCALER_CLIENT_SECRET": "your-client-secret",
        "ZSCALER_CUSTOMER_ID": "your-customer-id",
        "ZSCALER_VANITY_DOMAIN": "your-vanity-domain"
      }
    }
  }
}

Docker Version

{
  "mcpServers": {
    "zscaler-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/full/path/to/.env",
        "zscaler/zscaler-mcp-server:latest"
      ]
    }
  }
}

Using the MCP Server with Agents

Once your server is running (via Docker or source), you can access its tools through AI-integrated editors or platforms.

Claude

  1. Open Claude

  2. In Chat, select the “Search & Tools”

  3. The server appears in the tools list zscaler-mcp-server

  4. Try prompts like “List ZPA Segment Groups” or “List ZIA Rule Labels”

  5. Select the tool and click “Submit”

Cursor

  1. Open Cursor, then settings

  2. In Cursor Settings, select “Tools & Integrations”

  3. In the MCP Tools section, turn on zscaler-mcp-server

  4. Select View and Command Palette and Chat: Open Chat Agent

  5. In chat, switch to Agent Mode.

  6. Try prompts like “List ZPA Segment Groups” or “List ZIA Rule Labels”

  7. Click “Submit”

Visual Studio Code + GitHub Copilot

Install

After installation, select GitHub Copilot Agent Mode and refresh the tools list. Learn more about Agent Mode in the VS Code Documentation.

  1. Open VS Code and launch GitHub Copilot

  2. Switch to Agent Mode (via the gear menu)

  3. Start the MCP Server

  4. Refresh the tools list

  5. Try a prompt like: Create a ZPA segment group named "DevServices"

📚 Learn more about Agent Mode in the VS Code Copilot documentation

Troubleshooting

See the Troubleshooting guide for help with common issues and logging.

Contributing

Getting Started for Contributors

  1. Clone the repository:

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

  2. Install in development mode:

    # Create .venv and install dependencies
uv sync --all-extras

# Activate the venv
source .venv/bin/activate

Important

This project uses Conventional Commits for automated releases and semantic versioning. Please follow the commit message format outlined in our Contributing Guide when submitting changes.

Running Tests

# Run all tests
pytest

# Run end-to-end tests
pytest --run-e2e tests/e2e/

# Run end-to-end tests with verbose output (note: -s is required to see output)
pytest --run-e2e -v -s tests/e2e/

License

Copyright (c) 2025 Zscaler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.