Falcon-MCP: MCP Protocol Server Connecting AI Agents to Falcon for Automated Security Analysis

Falcon MCP

falcon-mcp is a Model Context Protocol server that connects AI agents to the CrowdStrike Falcon platform, providing programmatic access to core security capabilities such as security detections, events, and behaviors, and supporting intelligent security analysis and automated workflows.

Security Developer tools #Security analysis #AI integration #Threat detection #Automation .Python

rating : 2.5 points

downloads : 9.4K

update time : 2025-08-15

Open Site

What is the Falcon MCP Server?

The Falcon MCP Server is a middleware service that acts as a bridge between AI agents and the CrowdStrike Falcon security platform. Through a standardized protocol, it enables AI systems to access key security capabilities such as security detections, events, and behavioral analysis from CrowdStrike.

How to use the Falcon MCP Server?

You can quickly start the server using a simple command-line tool or a Docker container, and then integrate it with your AI system through a standard protocol. The server supports multiple transmission methods, including stdio, SSE, and HTTP streaming.

Use cases

Suitable for scenarios such as security operations automation, threat intelligence analysis, security incident response, and vulnerability management. Particularly suitable for environments that need to integrate AI capabilities with Security Operations Center (SOC) workflows.

Main features

Cloud security analysis

Provides the ability to search and analyze vulnerabilities in Kubernetes containers and images.

Threat detection

Search and analyze security detection events to understand malicious activities in the environment.

Incident management

Analyze security incidents and associated behaviors to understand attack patterns and coordinated activities.

Identity protection

Comprehensive entity investigation tool that supports timeline analysis and risk assessment.

Threat intelligence

Research threat actors, IOCs, and intelligence reports.

Advantages

Simplifies the integration of AI systems with the CrowdStrike platform.

Modular design, allowing functions to be enabled on demand.

Supports multiple transmission protocols to adapt to different usage scenarios.

Provides detailed query documentation and examples.

Limitations

Currently in public preview, and features may change.

Requires CrowdStrike API credentials and appropriate permissions.

The FQL query syntax has a certain learning curve.

How to use

Get API credentials

Create an API client in the CrowdStrike console and obtain the necessary permission scopes.

Configure the environment

Set environment variables or create an.env file containing your API credentials.

Install the server

Install the falcon-mcp package using pip or uv.

Run the server

Select the required modules and transmission method to start the server.

Usage examples

Threat detection analysis

Use an AI system to analyze recent threat detection events.

Vulnerability assessment

Identify systems with critical vulnerabilities in the environment.

Identity risk investigation

Investigate the risk status and activity timeline of a specific user.

Frequently Asked Questions

How to obtain the necessary API permissions?

Which regions does the server support?

How to verify if the server is working properly?

Can multiple modules be used simultaneously?

How to contribute code or report issues?

Related resources

GitHub repository

Project source code and issue tracking

CrowdStrike API documentation

Official API documentation and reference

FalconPy library

CrowdStrike official Python SDK

MCP protocol specification

Model Context Protocol standard documentation

🚀 falcon-mcp

falcon-mcp is a Model Context Protocol (MCP) server that connects AI agents with the CrowdStrike Falcon platform, enabling intelligent security analysis in your agentic workflows. It offers programmatic access to essential security capabilities, such as detections, incidents, and behaviors, laying the groundwork for advanced security operations and automation.

⚠️ Important Note

🚧 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.

🚀 Quick Start

To quickly get started with falcon-mcp, you need to set up your API credentials, install the necessary dependencies, and configure your environment. For detailed steps, refer to the Installation & Setup section below.

✨ Features

Multiple Modules: Offers a variety of modules for different security use - cases, including cloud security, detections, incidents, and more.
FQL Guide Resources: Some modules come with FQL guide resources for comprehensive query documentation and examples.
Flexible Deployment: Can be installed via different methods like uv or pip, and can be run as a command - line tool, a library, or in a container.
Editor/Assistant Integration: Supports integration with editors and AI assistants for seamless usage.

📦 Installation

Prerequisites

Python 3.11 or higher
uv or pip
CrowdStrike Falcon API credentials (see API Credentials & Required Scopes)

Environment Configuration

You can configure your CrowdStrike API credentials in several ways:

Use a `.env` File

Option 1: Copy from cloned repository (if you've cloned it)

cp .env.example .env

Option 2: Download the example file from GitHub

curl -o .env https://raw.githubusercontent.com/CrowdStrike/falcon-mcp/main/.env.example

Option 3: Create manually with the following content

# Required Configuration
FALCON_CLIENT_ID=your-client-id
FALCON_CLIENT_SECRET=your-client-secret
FALCON_BASE_URL=https://api.crowdstrike.com

# Optional Configuration (uncomment and modify as needed)
#FALCON_MCP_MODULES=detections,incidents,intel
#FALCON_MCP_TRANSPORT=stdio
#FALCON_MCP_DEBUG=false
#FALCON_MCP_HOST=127.0.0.1
#FALCON_MCP_PORT=8000

Environment Variables

Set the following environment variables in your shell:

# Required Configuration
export FALCON_CLIENT_ID="your-client-id"
export FALCON_CLIENT_SECRET="your-client-secret"
export FALCON_BASE_URL="https://api.crowdstrike.com"

# Optional Configuration
export FALCON_MCP_MODULES="detections,incidents,intel"  # Comma-separated list (default: all modules)
export FALCON_MCP_TRANSPORT="stdio"                     # Transport method: stdio, sse, streamable-http
export FALCON_MCP_DEBUG="false"                         # Enable debug logging: true, false
export FALCON_MCP_HOST="127.0.0.1"                      # Host for HTTP transports
export FALCON_MCP_PORT="8000"                           # Port for HTTP transports

CrowdStrike API Region URLs:

US - 1 (Default): https://api.crowdstrike.com
US - 2: https://api.us-2.crowdstrike.com
EU - 1: https://api.eu-1.crowdstrike.com
US - GOV: https://api.laggar.gcw.crowdstrike.com

Installation

Install using uv

uv tool install falcon-mcp

Install using pip

pip install falcon-mcp

💡 Usage Tip

If falcon-mcp isn't found, update your shell PATH.

💻 Usage Examples

Command Line

Run the server with default settings (stdio transport):

falcon-mcp

Run with SSE transport:

falcon-mcp --transport sse

Run with streamable-http transport:

falcon-mcp --transport streamable-http

Run with streamable-http transport on custom port:

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

Module Configuration

The Falcon MCP Server supports multiple ways to specify which modules to enable:

1. Command Line Arguments (highest priority)

Specify modules using comma-separated lists:

# Enable specific modules
falcon-mcp --modules detections,incidents,intel,spotlight,idp

# Enable only one module
falcon-mcp --modules detections

2. Environment Variable (fallback)

Set the FALCON_MCP_MODULES environment variable:

# Export environment variable
export FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp
falcon-mcp

# Or set inline
FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp

3. Default Behavior (all modules)

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

Module Priority Order:

Command line --modules argument (overrides all)
FALCON_MCP_MODULES environment variable (fallback)
All modules (default when none specified)

Additional Command Line Options

For all available options:

falcon-mcp --help

As a Library

from falcon_mcp.server import FalconMCPServer

# Create and run the server
server = FalconMCPServer(
    base_url="https://api.us-2.crowdstrike.com",  # Optional, defaults to env var
    debug=True,  # Optional, enable debug logging
    enabled_modules=["detections", "incidents", "spotlight", "idp"]  # Optional, defaults to all modules
)

# Run with stdio transport (default)
server.run()

# Or run with SSE transport
server.run("sse")

# Or run with streamable-http transport
server.run("streamable-http")

# Or run with streamable-http transport on custom host/port
server.run("streamable-http", host="0.0.0.0", port=8080)

Running Examples

# Run with stdio transport
python examples/basic_usage.py

# Run with SSE transport
python examples/sse_usage.py

# Run with streamable-http transport
python examples/streamable_http_usage.py

📚 Documentation

API Credentials & Required Scopes

Setting Up CrowdStrike API Credentials

Before using the Falcon MCP Server, you need to create API credentials in your CrowdStrike console:

Log into your CrowdStrike console
Navigate to Support > API Clients and Keys
Click "Add new API client"
Configure your API client:
- Client Name: Choose a descriptive name (e.g., "Falcon MCP Server")
- Description: Optional description for your records
- API Scopes: Select the scopes based on which modules you plan to use (see below)

⚠️ Important Note

Ensure your API client has the necessary scopes for the modules you plan to use. You can always update scopes later in the CrowdStrike console.

Required API Scopes by Module

The Falcon MCP Server supports different modules, each requiring specific API scopes:

Module	Required API Scopes	Purpose
Cloud Security	`Falcon Container Image:read`	Find and analyze kubernetes containers inventory and container imges vulnerabilities
Core	No additional scopes	Basic connectivity and system information
Detections	`Alerts:read`	Find and analyze detections to understand malicious activity
Discover	`Assets:read`	Search and analyze application inventory across your environment
Hosts	`Hosts:read`	Manage and query host/device information
Identity Protection	`Identity Protection Entities:read` `Identity Protection Timeline:read` `Identity Protection Detections:read` `Identity Protection Assessment:read`	Comprehensive entity investigation and identity protection analysis
Incidents	`Incidents:read`	Analyze security incidents and coordinated activities
Intel	`Actors (Falcon Intelligence):read` `Indicators (Falcon Intelligence):read` `Reports (Falcon Intelligence):read`	Research threat actors, IOCs, and intelligence reports
Sensor Usage	`Sensor Usage:read`	Access and analyze sensor usage data
Serverless	`Falcon Container Image:read`	Search for vulnerabilities in serverless functions across cloud service providers
Spotlight	`Vulnerabilities:read`	Manage and analyze vulnerability data and security assessments

Available Modules, Tools & Resources

⚠️ Important Note on FQL Guide Resources

Several modules include FQL (Falcon Query Language) guide resources that provide comprehensive query documentation and examples. While these resources are designed to assist AI assistants and users with query construction, FQL has nuanced syntax requirements and field - specific behaviors that may not be immediately apparent. AI - generated FQL filters should be tested and validated before use in production environments. We recommend starting with simple queries and gradually building complexity while verifying results in a test environment first.

About Tools & Resources: This server provides both tools (actions you can perform) and resources (documentation and context). Tools execute operations like searching for detections or analyzing threats, while resources provide comprehensive documentation like FQL query guides that AI assistants can reference for context without requiring tool calls.

Cloud Security Module

API Scopes Required:

Falcon Container Image:read

Provides tools for accessing and analyzing CrowdStrike Cloud Security resources:

falcon_search_kubernetes_containers: Search for containers from CrowdStrike Kubernetes & Containers inventory
falcon_count_kubernetes_containers: Count for containers by filter criteria from CrowdStrike Kubernetes & Containers inventory
falcon_search_images_vulnerabilities: Search for images vulnerabilities from CrowdStrike Image Assessments

Resources:

falcon://cloud/kubernetes-containers/fql-guide: Comprehensive FQL documentation and examples for kubernetes containers searches
falcon://cloud/images-vulnerabilities/fql-guide: Comprehensive FQL documentation and examples for images vulnerabilities searches

Use Cases: Manage kubernetes containers inventory, container images vulnerabilities analysis

Core Functionality (Built into Server)

API Scopes: None required beyond basic API access

The server provides core tools for interacting with the Falcon API:

falcon_check_connectivity: Check connectivity to the Falcon API
falcon_list_enabled_modules: Lists enabled modules in the falcon - mcp server

These modules are determined by the --modules flag when starting the server. If no modules are specified, all available modules are enabled.
falcon_list_modules: Lists all available modules in the falcon - mcp server

Detections Module

API Scopes Required: Alerts:read

Provides tools for accessing and analyzing CrowdStrike Falcon detections:

falcon_search_detections: Find and analyze detections to understand malicious activity in your environment
falcon_get_detection_details: Get comprehensive detection details for specific detection IDs to understand security threats

Resources:

falcon://detections/search/fql-guide: Comprehensive FQL documentation and examples for detection searches

Use Cases: Threat hunting, security analysis, incident response, malware investigation

Discover Module

API Scopes Required: Assets:read

Provides tools for accessing and managing CrowdStrike Falcon Discover applications and unmanaged assets:

falcon_search_applications: Search for applications in your CrowdStrike environment
falcon_search_unmanaged_assets: Search for unmanaged assets (systems without Falcon sensor installed) that have been discovered by managed systems

Resources:

falcon://discover/applications/fql-guide: Comprehensive FQL documentation and examples for application searches
falcon://discover/hosts/fql-guide: Comprehensive FQL documentation and examples for unmanaged assets searches

Use Cases: Application inventory management, software asset management, license compliance, vulnerability assessment, unmanaged asset discovery, security gap analysis

Hosts Module

API Scopes Required: Hosts:read

Provides tools for accessing and managing CrowdStrike Falcon hosts/devices:

falcon_search_hosts: Search for hosts in your CrowdStrike environment
falcon_get_host_details: Retrieve detailed information for specified host device IDs

Resources:

falcon://hosts/search/fql-guide: Comprehensive FQL documentation and examples for host searches

Use Cases: Asset management, device inventory, host monitoring, compliance reporting

Identity Protection Module

API Scopes Required: Identity Protection GraphQL:write

Provides tools for accessing and managing CrowdStrike Falcon Identity Protection capabilities:

idp_investigate_entity: Entity investigation tool for analyzing users, endpoints, and other entities with support for timeline analysis, relationship mapping, and risk assessment

Use Cases: Entity investigation, identity protection analysis, user behavior analysis, endpoint security assessment, relationship mapping, risk assessment

Incidents Module

API Scopes Required: Incidents:read

Provides tools for accessing and analyzing CrowdStrike Falcon incidents:

falcon_show_crowd_score: View calculated CrowdScores and security posture metrics for your environment
falcon_search_incidents: Find and analyze security incidents to understand coordinated activity in your environment
falcon_get_incident_details: Get comprehensive incident details to understand attack patterns and coordinated activities
falcon_search_behaviors: Find and analyze behaviors to understand suspicious activity in your environment
falcon_get_behavior_details: Get detailed behavior information to understand attack techniques and tactics

Resources:

falcon://incidents/crowd-score/fql-guide: Comprehensive FQL documentation for CrowdScore queries
falcon://incidents/search/fql-guide: Comprehensive FQL documentation and examples for incident searches
falcon://incidents/behaviors/fql-guide: Comprehensive FQL documentation and examples for behavior searches

Use Cases: Incident management, threat assessment, attack pattern analysis, security posture monitoring

Intel Module

API Scopes Required:

Actors (Falcon Intelligence):read
Indicators (Falcon Intelligence):read
Reports (Falcon Intelligence):read

Provides tools for accessing and analyzing CrowdStrike Intelligence:

falcon_search_actors: Research threat actors and adversary groups tracked by CrowdStrike intelligence
falcon_search_indicators: Search for threat indicators and indicators of compromise (IOCs) from CrowdStrike intelligence
falcon_search_reports: Access CrowdStrike intelligence publications and threat reports

Resources:

falcon://intel/actors/fql-guide: Comprehensive FQL documentation and examples for threat actor searches
falcon://intel/indicators/fql-guide: Comprehensive FQL documentation and examples for indicator searches
falcon://intel/reports/fql-guide: Comprehensive FQL documentation and examples for intelligence report searches

Use Cases: Threat intelligence research, adversary tracking, IOC analysis, threat landscape assessment

Sensor Usage Module

API Scopes Required: Sensor Usage:read

Provides tools for accessing and analyzing CrowdStrike Falcon sensor usage data:

falcon_search_sensor_usage: Search for weekly sensor usage data in your CrowdStrike environment

Resources:

falcon://sensor-usage/weekly/fql-guide: Comprehensive FQL documentation and examples for sensor usage searches

Use Cases: Sensor deployment monitoring, license utilization analysis, sensor health tracking

Serverless Module

API Scopes Required: Falcon Container Image:read

Provides tools for accessing and managing CrowdStrike Falcon Serverless Vulnerabilities:

falcon_search_serverless_vulnerabilities: Search for vulnerabilities in your serverless functions across all cloud service providers

Resources:

falcon://serverless/vulnerabilities/fql-guide: Comprehensive FQL documentation and examples for serverless vulnerabilities searches

Use Cases: Serverless security assessment, vulnerability management, cloud security monitoring

Spotlight Module

API Scopes Required: Vulnerabilities:read

Provides tools for accessing and managing CrowdStrike Spotlight vulnerabilities:

falcon_search_vulnerabilities: Search for vulnerabilities in your CrowdStrike environment

Resources:

falcon://spotlight/vulnerabilities/fql-guide: Comprehensive FQL documentation and examples for vulnerability searches

Use Cases: Vulnerability management, security assessments, compliance reporting, risk analysis, patch prioritization

Container Usage

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

Using Pre - built Image (Recommended)

# Pull the latest pre-built image
docker pull quay.io/crowdstrike/falcon-mcp:latest

# Run with .env file (recommended)
docker run --rm --env-file /path/to/.env quay.io/crowdstrike/falcon-mcp:latest

# Run with .env file and SSE transport
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  quay.io/crowdstrike/falcon-mcp:latest --transport sse --host 0.0.0.0

# Run with .env file and streamable-http transport
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  quay.io/crowdstrike/falcon-mcp:latest --transport streamable-http --host 0.0.0.0

# Run with .env file and custom port
docker run --rm -p 8080:8080 --env-file /path/to/.env \
  quay.io/crowdstrike/falcon-mcp:latest --transport streamable-http --host 0.0.0.0 --port 8080

# Run with .env file and specific modules
docker run --rm --env-file /path/to/.env \
  quay.io/crowdstrike/falcon-mcp:latest --modules detections,incidents,spotlight,idp

# Use a specific version instead of latest
docker run --rm --env-file /path/to/.env \
  quay.io/crowdstrike/falcon-mcp:1.2.3

# Alternative: Individual environment variables
docker run --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret \
  quay.io/crowdstrike/falcon-mcp:latest

Building Locally (Development)

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

# Build the Docker image
docker build -t falcon-mcp .

# Run the locally built image
docker run --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret falcon-mcp

⚠️ Important 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 Falcon MCP server with your editor or AI assistant. Here are configuration examples for popular MCP clients:

Using `uvx` (recommended)

{
  "mcpServers": {
    "falcon-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "falcon-mcp"
      ]
    }
  }
}

With Module Selection

{
  "mcpServers": {
    "falcon-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "falcon-mcp",
        "--modules",
        "detections,incidents,intel"
      ]
    }
  }
}

Using Individual Environment Variables

{
  "mcpServers": {
    "falcon-mcp": {
      "command": "uvx",
      "args": ["falcon-mcp"],
      "env": {
        "FALCON_CLIENT_ID": "your-client-id",
        "FALCON_CLIENT_SECRET": "your-client-secret",
        "FALCON_BASE_URL": "https://api.crowdstrike.com"
      }
    }
  }
}

Docker Version

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

Additional Deployment Options

Amazon Bedrock AgentCore

To deploy the MCP Server as a tool in Amazon Bedrock AgentCore, please refer to the following document.

🔧 Technical Details

The Falcon MCP server is built on top of the CrowdStrike Falcon API and provides a unified interface for AI agents to interact with various security capabilities. It uses the Falcon Query Language (FQL) for querying data from different modules. Each module has specific API scopes that need to be configured correctly to access the corresponding functionality.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

This is a community - driven, open source project. While it is not an official CrowdStroke product, it is actively maintained by CrowdStrike and supported in collaboration with the open source developer community.

For more information, please see our SUPPORT file.