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