IBM QRadar MCP Server - Official

August 26, 2026 · View on GitHub

An open-source Model Context Protocol (MCP) server implementation for IBM QRadar SIEM that enables AI agents to interact with QRadar SIEM data through standardized tools and protocols.

License Python

Overview

The QRadar MCP Server provides AI agents with standardized access to IBM QRadar SIEM capabilities, including offenses, events and flows, reference data, assets, analytics, configuration, and other security context.

The server can be deployed standalone using Docker or run locally for development. When used with IBM QRadar Investigation Assistant (QIA), the MCP Server can also be exposed directly through the QIA application using QRadar App Framework namespaces, enabling external MCP-compatible clients to connect without requiring deployment of a separate QRadar MCP application.

This enables integrations with MCP-compatible AI platforms and agents while keeping QRadar access and MCP capabilities within the QIA deployment model..

Project Structure

qradar-mcp/
├── client/            # QRadar REST API client
├── tools/             # MCP tools
├── resources/         # MCP resources
├── utils/             # Utilities (auth, logging, validation)
├── tests/             # Comprehensive test suite
├── server.py          # Main server entry point
└── Dockerfile         # Container configuration

Features

  • FastMCP Framework: Modern, async-first MCP server implementation with uvicorn (ASGI)
  • MCP Protocol Compliance: Full implementation of Model Context Protocol specification
  • 83 Tools: Comprehensive QRadar API coverage across read and write operations
    • Offense Management (12 tools) - List, retrieve, close, assign, and annotate offenses
    • Reference Data (19 tools) - Create, query, update, and delete reference sets, maps, and tables
    • Data Classification (13 tools) - Manage DSM event mappings, QID records, and categories
    • Ariel Search (8 tools) - Execute AQL queries, poll status, retrieve results, and manage saved searches
    • Config Management (9 tools) - Network hierarchy, staged networks, deploy, and user management
    • Analytics (6 tools) - Retrieve rules, building blocks, and custom actions
    • Log Sources (3 tools) - Query log source configurations and types
    • Network Services (5 tools) - DNS lookup, WHOIS lookup, and IP geolocation
    • Asset Management (2 tools) - List assets and properties
    • Forensics (2 tools) - Query forensics cases
    • QVM (2 tools) - Vulnerability and asset data
    • System Administration (2 tools) - System info and server listing
  • Dynamic Resources: AQL field definitions, functions, generation guide, and API query syntax reference
  • Dual Authentication: Supports both user sessions and authorized service tokens

Deployment

The QRadar MCP Server can be deployed in multiple ways depending on your needs.

Prerequisites

  • Docker 20.10+ and Docker Compose 2.0+ (for containerized deployment)
  • Python 3.11+ (for local development)
  • Access to a QRadar SIEM deployment
  • QRadar SIEM authentication tokens (SEC/CSRF or Authorized Service token)

The easiest way to deploy the MCP server is using Docker Compose. The server can be run in two modes:

  • Local Single User Mode: Utilizes config.json on the disk to authenticate all incoming requests (useful for local development).
  • Multi User Mode (App Mode): Does not use or mount config.json. Every client request must supply its own QRadar credentials via headers (SEC and QRadarCSRF, or Authorized service token as SEC).

Setup for Local Single User Mode:

  1. Clone the repository and navigate to the directory:

    git clone https://github.com/IBM/qradar-mcp.git
cd qradar-mcp

  2. Create configuration file:

    cp config.example.json config.json
# Edit config.json with your QRadar credentials

  3. Set environment variables: Create a .env file:

    cat > .env << EOF
QRADAR_HOST=your-qradar-host.com
LOG_LEVEL=info
EOF

  4. Start the server:

    docker-compose up -d

  5. View logs:

    docker-compose logs -f qradar-mcp

  6. Stop the server:

    docker-compose down

The server will be available at http://localhost:5001 (mapped from internal port 5000).

Setup for Multi User Mode:

To run the server in multi user mode where no config.json is present or mounted on the container.

  1. Clone the repository and navigate to the directory:

    git clone https://github.com/IBM/qradar-mcp.git
cd qradar-mcp

  2. Set environment variables and disable the volume mount: Create a .env file:

    cat > .env << EOF
QRADAR_HOST=your-qradar-host.com
LOG_LEVEL=info
EOF

    Modify docker-compose.yml to remove or comment out the config.json volume mount block under volumes:

    # - ./config.json:/opt/app-root/qradar-mcp/config.json:ro

  3. Configure SSL Verification via REQUESTS_CA_BUNDLE: In multi-user production deployments, secure SSL/TLS communication with QRadar is highly recommended. To enable SSL certificate verification, set the REQUESTS_CA_BUNDLE environment variable in your .env file to point to the path of your trusted CA certificate file/bundle inside the container, or pass it via the system environment.

    echo "REQUESTS_CA_BUNDLE=/path/to/your/ca-bundle.crt" >> .env

  4. Start the server:

    docker-compose up -d

Option 2: Manual Docker Build

For more control over the Docker deployment:

  1. Build the image:

    docker build -t qradar-mcp:latest .

  2. Run the container in Local Single User Mode:

    docker run -d \
  --name qradar-mcp-server \
  -p 5001:5000 \
  -e LOG_LEVEL=info \
  -v $(pwd)/config.json:/opt/app-root/config.json:ro \
  -v $(pwd)/logs:/opt/app-root/logs \
  qradar-mcp:latest

    Note: In this mode, the container mounts config.json to authenticate all requests using those credentials.

  3. Run the container in Multi User Mode:

    docker run -d \
  --name qradar-mcp-server \
  -p 5001:5000 \
  --env-file .env \
  -v $(pwd)/logs:/opt/app-root/logs \
  qradar-mcp:latest

    Note: In App Mode, every client request must supply its own user session or service credentials in the HTTP request headers (SEC and/or QRadarCSRF). Environment variables (including QRADAR_CONSOLE_FQDN and REQUESTS_CA_BUNDLE) are loaded from the .env file created in the setup steps above.

  4. Check status:

    docker ps
docker logs qradar-mcp-server

Option 3: Run Local with Python

For local development with Python without Docker:

  1. Create virtual environment (recommended):

    python3 -m venv venv
source venv/bin/activate

  2. Install dependencies:

    pip install -e .

  3. Configure authentication for local single user mode:

    cp config.example.json config.json
# Edit config.json with your QRadar credentials

# Copy config to parent directory (required for local mode)
cp config.json ../config.json

    Note: Moving or copying config.json to the parent directory (../config.json) tells the application to run in Local Mode. In Local Mode, the client falls back to the credentials configured in config.json for requests that do not supply their own credentials. Should not be done in production or shared multi user environments.

  4. Run the server:

    python server.py

The server will start at http://localhost:5000. The port can be modified in server.py if port conflicts occur.

Verify Deployment

Use the provided test script to verify your deployment:

# Run the connection test
python tests/local_mcp_connection.py

This script will:

  1. Load authentication from your config.json
  2. Connect to the MCP server at http://localhost:5001
  3. Initialize the MCP session
  4. List all available tools
  5. Display the first 10 tools

Expected output:

QRadar MCP Server - Local Container Test
==================================================
Endpoint: http://localhost:5001/mcp
Auth: Using authorized service token from config.json
...
✅ Found 32 tools
==================================================
✅ MCP Server is fully operational in local mode!
==================================================

Configuration

Environment Variables

  • QRADAR_HOST: QRadar instance hostname
  • QRADAR_SEC_TOKEN: QRadar SEC token (for user sessions)
  • QRADAR_CSRF_TOKEN: QRadar CSRF token (for user sessions)
  • QRADAR_AUTH_TOKEN: Authorized service token (alternative to SEC/CSRF)

Configuration Files

  • config.json: Main configuration (not committed)
  • config.example.json: Configuration template
  • mcp_settings.json: MCP-specific settings (not committed)
  • mcp_settings.example.json: Settings template

Security

  • Never commit config.json or mcp_settings.json - They contain sensitive tokens.
  • Deployment modes: Only use the config.json files for local single user development. In multi user or production deployments, do not place or mount config.json in the expected lookup paths. This ensures the server runs in secure multi user mode, where all API requests are verified using the user's/service's own request context headers.
  • SSL Certificate Verification: In production, always configure SSL validation by pointing the REQUESTS_CA_BUNDLE environment variable to the path of your trusted CA certificates bundle file (e.g., /etc/ssl/certs/ca-certificates.crt). Disabling SSL verification is insecure and should only be done for experimentation or local development.
  • Tokens are session-based and expire - refresh as needed.
  • All endpoints require authentication.
  • Supports both user sessions and authorized service tokens.

Troubleshooting

Common Issues

  • Authentication errors (401): Refresh your QRadar tokens
  • Connection refused: Verify QRadar host is accessible
  • SSL errors: Set verify_ssl: false for testing
  • Tool not found: Ensure MCP server is properly initialized

IBM QRadar Investigation Assistant

IBM QRadar Investigation Assistant uses this QRadar SIEM MCP server to accelerate your SOC operations - out of the box.

Download the IBM QRadar Investigation Assistant application extension from the IBM Application Exchange here

Community

License

Copyright 2026 IBM Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

IBM Public Repository Disclosure

All content in these repositories including code has been provided by IBM under the associated open source software license and IBM is under no obligation to provide enhancements, updates, or support. IBM developers produced this code as an open source project (not as an IBM product), and IBM makes no assertions as to the level of quality nor security, and will not be maintaining this code going forward.