IBM QRadar MCP Server - Official

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.

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          # HTTP server entry point (Docker / uvicorn)
├── stdio_server.py    # stdio transport entry point (WxO local toolkit, Claude Desktop)
└── 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
• Flexible Authentication: Supports user sessions (SEC/CSRF), authorized service tokens, and HTTP Basic username/password

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 credentials (SEC/CSRF tokens, an Authorized Service token, or a username/password for HTTP Basic)

Option 1: Docker Compose (Recommended)

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, Authorized service token as SEC, or Authorization: Basic <base64(user:password)>).

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.

   Fill in exactly one credential set under qradar — see Authentication for the available options and their precedence.

4. Run the server:

   python server.py

The server will start at http://localhost:5000 by default. The bind address and port are resolved in this order, so an unconfigured deployment keeps the historical 0.0.0.0:5000:

1. The MCP_HOST and MCP_PORT environment variables
2. The server.host and server.port keys in config.json
3. The defaults 0.0.0.0 and 5000

# Via environment variables
MCP_PORT=8080 python server.py

# Or via config.json
#   "server": { "host": "127.0.0.1", "port": 8080 }

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)
• QRADAR_USERNAME: Username for HTTP Basic authentication (used only when no token is set)
• QRADAR_PASSWORD: Password for HTTP Basic authentication (required with QRADAR_USERNAME)
• MCP_HOST: Bind address for the HTTP server (default 0.0.0.0; overrides server.host)
• MCP_PORT: Listen port for the HTTP server (default 5000; overrides server.port)

Authentication

The server supports three credential types. They can be supplied per request via HTTP headers (Multi User Mode), from config.json (Local Single User Mode), or from the QRADAR_* environment variables (stdio transport, or a container with no config.json):

Credential type	config.json fields	Environment variables	HTTP headers
Authorized service token	authorized_service_token	QRADAR_AUTH_TOKEN	SEC: <token>
User session	sec_token, csrf_token	QRADAR_SEC_TOKEN, QRADAR_CSRF_TOKEN	SEC: <token>, QRadarCSRF: <token>
HTTP Basic	username, password	QRADAR_USERNAME, QRADAR_PASSWORD	Authorization: Basic <base64(username:password)>

Precedence, applied identically to every source:

1. Authorized service token
2. User session tokens (sec_token / csrf_token)
3. HTTP Basic credentials

Credentials supplied per request always take precedence over the ones this process was started with. Only the Basic scheme is read from the Authorization header — an Authorization: Bearer ... header (for example, one used to authenticate to the MCP server itself) is never forwarded to QRadar.

A Multi User Mode deployment configures none of the above, so a request that carries no credentials of its own is rejected exactly as before.

HTTP Basic sends reusable credentials on every request, so prefer an authorized service token where one can be issued, and always enable TLS verification when using it.

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

Documentation

• watsonx Orchestrate Integration Guide - Full reference covering all three integration patterns (QIA embedded MCP, standalone external server, and WxO local MCP toolkit), network diagrams, environment variable reference, and troubleshooting.

Community

• Issues: Report bugs or request features via GitHub Issues

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.