CrowdStrike Falcon MCP Server

A Model Context Protocol (MCP) server for interacting with the CrowdStrike Falcon API. This server provides both STDIO (for MCP-aware clients) and HTTP/REST (for broader interoperability) transport modes.

Features

Dual Transport Support: Supports both STDIO (MCP protocol) and HTTP/REST simultaneously
Secure Credential Handling: Credentials can be passed as function parameters or via environment variables
Multi-tenant Support: Optional tenant ID support for multi-tenant scenarios
Comprehensive API Coverage: Tools for hosts, detections, IOCs, policies, and more
Production Ready: Docker support with health checks and GitHub Actions CI/CD

Architecture

┌─────────────────┐      ┌──────────────┐      ┌─────────────────┐
│ MCP Client      │─────▶│ STDIO Port   │─────▶│ MCP Core        │
│ (Claude/Cursor) │      │ (8080)       │      │ (FastMCP)       │
└─────────────────┘      └──────────────┘      └─────────────────┘
                                                       │
┌─────────────────┐      ┌──────────────┐            │
│ REST Client     │─────▶│ HTTP Gateway │─────────────┘
│ (curl/Python)   │      │ (Port 80)    │
└─────────────────┘      └──────────────┘

Installation

Docker (Recommended)

docker pull <your-registry>/crowdstrike-falcon-mcp:latest
docker run -d \
  --name crowdstrike-falcon-mcp \
  --publish 8080:8080 \
  --publish 80:80 \
  -e TRANSPORT_MODE=dual \
  -e FALCON_API_KEY=your_api_key_here \
  <your-registry>/crowdstrike-falcon-mcp:latest

Configuration

Environment Variables

FALCON_API_KEY (or CROWDSTRIKE_API_KEY): Your CrowdStrike API key
FALCON_TENANT_ID (or CROWDSTRIKE_TENANT_ID): Optional tenant ID for multi-tenant scenarios
FALCON_API_BASE_URL: API base URL (default: https://api.crowdstrike.com)
TRANSPORT_MODE: Transport mode - stdio, http, or dual (default: dual)
HTTP_PORT: HTTP server port (default: 80)
STDIO_PORT: STDIO port (default: 8080)

Credential Handling

Security Note: Credentials are never stored. They can be provided in two ways:

Function Parameters: Pass api_key and optional tenant_id to each tool call
Environment Variables: Set FALCON_API_KEY and optionally FALCON_TENANT_ID

Connection Methods

1. STDIO (MCP Protocol)

For MCP-aware clients like Claude Desktop, Cursor, or MCP Toolkit.

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "crowdstrike-falcon": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "<your-registry>/crowdstrike-falcon-mcp:latest",
        "python",
        "-m",
        "src.mcp_server"
      ],
      "env": {
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}

Cursor

Similar configuration in Cursor's MCP settings.

MCP Toolkit

The mcp-toolkit.yml file enables automatic discovery. Place it in your MCP Toolkit configuration directory.

2. HTTP/REST API

For REST clients, curl, Python requests, Node.js fetch, etc.

Health Check

curl http://localhost:80/healthz

List Available Tools

curl http://localhost:80/tools

Call a Tool

curl -X POST http://localhost:80/tools/query_hosts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "filter": "hostname:\"example.com\"",
    "limit": 10
  }'

Python Example

import requests

# Using header for API key
response = requests.post(
    "http://localhost:80/tools/query_hosts",
    headers={"X-API-Key": "your_api_key_here"},
    json={"filter": "hostname:\"example.com\"", "limit": 10}
)
print(response.json())

# Or using body
response = requests.post(
    "http://localhost:80/tools/query_hosts",
    json={
        "api_key": "your_api_key_here",
        "filter": "hostname:\"example.com\"",
        "limit": 10
    }
)
print(response.json())

Node.js Example

const fetch = require('node-fetch');

async function queryHosts() {
  const response = await fetch('http://localhost:80/tools/query_hosts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key_here'
    },
    body: JSON.stringify({
      filter: 'hostname:"example.com"',
      limit: 10
    })
  });
  
  const data = await response.json();
  console.log(data);
}

queryHosts();

Available Tools

Host/Device Management

query_hosts: Query hosts/devices with filters
get_host_details: Get detailed information about specific hosts

Detection Management

query_detections: Query detections with filters
get_detection_details: Get detailed information about specific detections
update_detection_status: Update detection status

IOC Management

query_iocs: Query Indicators of Compromise
create_ioc: Create a new IOC
delete_ioc: Delete IOCs

Host Group Management

query_host_groups: Query host groups
get_host_group_details: Get detailed information about host groups

Policy Management

query_prevention_policies: Query prevention policies
get_prevention_policy_details: Get detailed information about prevention policies
query_sensor_update_policies: Query sensor update policies
get_sensor_update_policy_details: Get detailed information about sensor update policies

Example Tool Calls

Query Hosts (STDIO/MCP)

When using MCP clients, tools are called directly:

# In MCP client context
result = await mcp.call_tool("query_hosts", {
    "api_key": "your_api_key",
    "filter": "hostname:'example.com'",
    "limit": 10
})

Query Hosts (HTTP/REST)

curl -X POST http://localhost:80/tools/query_hosts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "filter": "hostname:\"example.com\"",
    "limit": 10
  }'

Create IOC

curl -X POST http://localhost:80/tools/create_ioc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "type": "domain",
    "value": "malicious.example.com",
    "action": "prevent",
    "platforms": ["Windows", "Mac", "Linux"],
    "description": "Malicious domain",
    "severity": "high"
  }'

Update Detection Status

curl -X POST http://localhost:80/tools/update_detection_status \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "detection_ids": ["detection_id_1", "detection_id_2"],
    "status": "true_positive",
    "comment": "Confirmed malicious activity"
  }'

HTTPS Deployment

Using nginx as Reverse Proxy

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Using Traefik

services:
  crowdstrike-falcon-mcp:
    image: <your-registry>/crowdstrike-falcon-mcp:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.falcon.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.falcon.tls=true"
      - "traefik.http.routers.falcon.tls.certresolver=letsencrypt"
      - "traefik.http.services.falcon.loadbalancer.server.port=80"

Production Deployment Considerations

Security:
- Use HTTPS in production
- Implement rate limiting
- Use API key rotation
- Monitor access logs
Scaling:
- Use a load balancer for HTTP mode
- Consider horizontal scaling for high traffic
- Use connection pooling for API calls
Monitoring:
- Monitor /healthz endpoint
- Set up alerting for failed health checks
- Log API errors and rate limits
High Availability:
- Deploy multiple instances
- Use health checks in orchestrators
- Implement graceful shutdown

Development

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest

Building Docker Image Locally

# Build
docker build -t crowdstrike-falcon-mcp:local .

# Run
docker run -p 8080:8080 -p 80:80 \
  -e FALCON_API_KEY=your_key \
  crowdstrike-falcon-mcp:local

Publishing Docker Image

# Using the script
python docker-publish.py \
  --registry docker.io \
  --image-name crowdstrike-falcon-mcp \
  --tag v1.0.0

# Or manually
docker build -t your-registry/crowdstrike-falcon-mcp:v1.0.0 .
docker push your-registry/crowdstrike-falcon-mcp:v1.0.0

GitHub Actions

The repository includes a GitHub Actions workflow (.github/workflows/docker-publish.yml) that automatically:

Builds Docker images on push to main/master
Builds and pushes on version tags
Supports multi-platform builds (amd64, arm64)
Uses Docker layer caching for faster builds

Required Secrets:

DOCKER_USERNAME: Your Docker Hub username
DOCKER_PASSWORD: Your Docker Hub password or access token

API Reference

CrowdStrike Falcon API

This MCP server wraps the CrowdStrike Falcon API. For detailed API documentation, refer to:

Filter Query Language (FQL)

Many endpoints support FQL (Falcon Query Language) for filtering. Examples:

hostname:'example.com' - Exact match
hostname:*example* - Wildcard match
status:'new'+severity:'high' - Multiple conditions
first_seen:>='2024-01-01T00:00:00Z' - Date comparison

Troubleshooting

Health Check Failing

# Check if server is running
curl http://localhost:80/healthz

# Check logs
docker logs crowdstrike-falcon-mcp

Authentication Errors

Verify your API key is correct
Check if API key has required scopes
Ensure API key format is correct (may be client_id:client_secret format)

Connection Issues

Verify ports are exposed correctly
Check firewall rules
Ensure TRANSPORT_MODE matches your use case

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

[Add your license here]

Support

For issues and questions:

Open an issue on GitHub
Check the CrowdStrike API documentation
Review the MCP server logs

Changelog

v1.0.0

Initial release
Support for hosts, detections, IOCs, policies
Dual transport mode (STDIO + HTTP)
Docker support
GitHub Actions CI/CD

CrowdStrike Falcon MCP Server

CrowdStrike Falcon MCP Server

Features

Architecture

Installation

Docker (Recommended)

Configuration

Environment Variables

Credential Handling

Connection Methods

1. STDIO (MCP Protocol)

Claude Desktop

Cursor

MCP Toolkit

2. HTTP/REST API

Health Check

List Available Tools

Call a Tool

Python Example

Node.js Example

Available Tools

Host/Device Management

Detection Management

IOC Management

Host Group Management

Policy Management

Example Tool Calls

Query Hosts (STDIO/MCP)

Query Hosts (HTTP/REST)

Create IOC

Update Detection Status

HTTPS Deployment

Using nginx as Reverse Proxy

Using Traefik

Production Deployment Considerations

Development

Running Tests

Building Docker Image Locally

Publishing Docker Image

GitHub Actions

API Reference

CrowdStrike Falcon API

Filter Query Language (FQL)

Troubleshooting

Health Check Failing

Authentication Errors

Connection Issues

Contributing

License

Support

Changelog

v1.0.0

Reviews