falcon-mcp

falcon-mcp는 AI 에이전트를 CrowdStrike Falcon 플랫폼에 연결하는 Model Context Protocol (MCP) 서버로, 에이전트 워크플로에서 지능형 보안 분석을 지원합니다. 탐지, 위협 인텔리전스, 호스트 관리 등 필수 보안 기능에 대한 프로그래밍 방식 액세스를 제공하여 고급 보안 운영 및 자동화의 기반을 마련합니다.

[!IMPORTANT] 🚧 공개 미리보기: 이 프로젝트는 현재 공개 미리보기 상태이며 활발히 개발 중입니다. 안정적인 1.0 릴리스 전에 기능이 변경될 수 있습니다. 탐색과 테스트를 권장하지만 프로덕션 배포는 피해 주시기 바랍니다. 최종 릴리스에 도움이 되도록 GitHub Issues를 통해 피드백을 환영합니다.

문서

전체 문서는 **developer.crowdstrike.com/falcon-mcp**에서 확인할 수 있습니다.

Related MCP server: falcon-mcp

모듈

필요한 API 범위, 사용 가능한 도구 및 FQL 리소스는 Module Overview를 참조하세요.

빠른 시작

설치

uv 사용 (권장)

uv tool install falcon-mcp

pip 사용

pip install falcon-mcp

구성

필요한 환경 변수를 설정하세요 (또는 .env 파일을 사용하세요 — Configuration Guide 참조):

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

실행

falcon-mcp

전체 설치 및 구성 세부 사항은 Getting Started 가이드를 참조하세요.

에디터 통합

uvx 사용 (권장)

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

모듈 선택

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

Docker

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

모든 명령줄 옵션, 모듈 구성 및 라이브러리 사용법은 Usage 가이드를 참조하세요.

컨테이너 사용

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

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

# Run with streamable-http transport (add --api-key when the port is reachable beyond localhost)
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 --api-key your-secret-key

[!CAUTION] HTTP 전송은 기본적으로 인증이 없습니다. 루프백이 아닌 주소(--host 0.0.0.0)에 바인딩하면 해당 포트에 도달할 수 있는 모든 사람이 CrowdStrike 자격 증명으로 구동할 수 있는 인증되지 않은 서버가 노출됩니다. 로컬 사용 시 기본 루프백 바인딩을 유지하고 더 넓은 범위에 바인딩할 때는 항상 --api-key를 설정하세요. AWS Bedrock AgentCore 및 Google Cloud Run과 같은 관리형 런타임은 자체 네트워크 보안 계층 뒤에 있으므로 이 사항이 적용되지 않습니다. Configuration 가이드를 참조하세요.

로컬 빌드, 사용자 지정 포트 및 고급 구성은 Docker Deployment 가이드를 참조하세요.

동적 모드

많은 모듈을 동시에 실행하면 모든 AI 클라이언트가 유지해야 하는 컨텍스트 창이 커집니다. 동적 모드는 전체 도구 표면을 세 가지 도구로 대체합니다 — 서버가 보유한 모든 도구를 확인하는 falcon_list_enabled_tools, 키워드로 후보 도구를 찾은 다음 선택한 도구의 매개변수 스키마를 가져오는 falcon_search_tools, 그리고 이를 실행하는 falcon_execute_tool — 에이전트는 실제로 필요한 스키마만 로드합니다.

falcon-mcp --dynamic
# or: FALCON_MCP_DYNAMIC=true

전체 검색 → 실행 워크플로와 장단점은 Dynamic Mode 가이드를 참조하세요.

서버가 수행할 수 있는 작업 제한

--modules는 모듈별로 전부 또는 전무(all-or-nothing) 방식입니다. 검색 도구를 얻기 위해 하나를 활성화하면 해당 모듈이 보유한 모든 변경 도구도 노출됩니다. 세 가지 도구 수준 옵션으로 그 표면을 좁힐 수 있습니다.

# Investigation-only server: no tool that mutates tenant state is registered
falcon-mcp --read-only

# Expose exactly two tools, nothing else
falcon-mcp --tools falcon_search_detections,falcon_search_hosts

# Keep the module, drop one tool
falcon-mcp --modules hostgroups --exclude-tools falcon_delete_host_groups

# All of detections, plus one tool from a module you did not enable
falcon-mcp --modules detections --tools falcon_search_applications

도구 이름은 클라이언트가 표시하는 falcon_ 접두사가 붙은 이름입니다. 인식할 수 없는 이름은 무시되지 않고 시작을 중단하므로 거부 목록의 오타가 도구를 조용히 노출된 상태로 둘 수 없습니다.

옵션 구성

--tools는 좁히는 필터가 아니라 추가적(additive) 입니다. --modules가 이미 활성화한 항목 위에 개별 도구를 부여하며 모듈 경계를 넘어 적용됩니다:

• --tools X 단독 사용은 X만 등록합니다 — 기본적으로 로드되는 모듈이 없습니다.

• --modules detections --tools X는 모든 detections 도구 및 X를 등록합니다. X가 활성화되지 않은 모듈에 속하더라도 마찬가지입니다. 해당 모듈은 전체 표면이 아닌 X만 기여하며 falcon_list_enabled_modules에는 나열되지 않습니다. falcon_list_enabled_tools에는 X가 나열됩니다 — 서버에서 사용 가능한 도구를 보고하므로 "이 기능을 여기서 사용할 수 있나요?"에 대한 신뢰할 수 있는 답변입니다.

빼려면 --exclude-tools 또는 --read-only를 사용하세요. 네 가지 옵션 모두 함께 구성할 수 있으며 고정된 순서로 해석됩니다:

1. --exclude-tools는 --tools가 이름을 지정하더라도 도구를 무조건 제거합니다.

2. --read-only는 --tools가 이름을 지정하더라도 모든 변경 도구를 무조건 제거합니다.

3. --tools는 모듈 게이트를 우회하여 이름이 지정된 도구를 추가합니다.

4. --modules는 기본적으로 어떤 도구가 후보가 될지 결정합니다.

처음 두 규칙이 항상 우선하므로 --read-only와 --exclude-tools는 배포 전반의 기본값으로 설정하기에 안전합니다. 추가적인 --tools 목록은 이를 넘어 확장할 수 없습니다. 이들을 결합하는 것이 "모든 것을 검색하고, 아무것도 변경하지 않으며, 그 특정 도구조차 제공하지 않기"를 표현하는 방법입니다:

falcon-mcp --read-only --exclude-tools falcon_execute_rtr_read_only_command

필터링은 동적 모드에도 적용됩니다 — 제외된 도구는 falcon_search_tools 결과에 없으며 falcon_execute_tool에서 거부됩니다. 동적 모드는 도구를 개별적으로 등록하는 대신 이름으로 디스패치하므로 해당 거부는 도구가 존재하지만 서버 구성이 이를 제외했음을 명시하고, 책임이 있는 단일 규칙을 이름으로 지정하므로 에이전트는 기능이 존재하지 않는다고 사용자에게 말하는 대신 비활성화된 도구를 비활성화된 것으로 보고합니다. falcon_list_enabled_tools는 규칙이 적용되는 경우 두 모드 모두에서 filters_active 필드를 전달합니다. 시작 로그는 어떤 규칙이 활성화되어 있고 --read-only와 --exclude-tools가 몇 개의 도구를 제외했는지 보고하므로 배포 내용을 확인할 수 있습니다. --debug로 실행하면 제외된 도구를 이름별로 볼 수 있습니다.

이러한 옵션은 도구를 필터링하지 리소스를 필터링하지 않습니다. 제외된 도구의 FQL 가이드 리소스는 계속 사용 가능합니다 — 가이드는 테넌트 데이터를 포함하지 않는 정적 필드 문서입니다.

배포 옵션

• Amazon Bedrock AgentCore

• Google Cloud (Agent Platform / Gemini Enterprise)

기여

# Clone and install
git clone https://github.com/CrowdStrike/falcon-mcp.git
cd falcon-mcp
uv sync --all-extras

# Run tests
uv run pytest

[!IMPORTANT] 이 프로젝트는 자동 릴리스를 위해 Conventional Commits을 사용합니다. Contributing Guide에 설명된 커밋 메시지 형식을 따라주세요.

개발자 문서

• 문서 가이드: 문서의 아키텍처 및 유지 관리 가이드

• 모듈 개발 가이드: 새 모듈 구현 지침

• 리소스 개발 가이드: 리소스 구현 지침

• 통합 테스트 가이드: 실제 API 호출로 통합 테스트를 실행하는 가이드

레지스트리

falcon-mcp는 호환 클라이언트에서 검색 및 원클릭 설정을 위해 공개 MCP 카탈로그에 게시됩니다:

• MCP Registry

• GitHub MCP Registry

• Gemini CLI Extensions

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 — 자세한 내용은 LICENSE 파일을 참조하세요.

지원

이 프로젝트는 커뮤니티 주도의 오픈 소스 프로젝트입니다. 공식 CrowdStrike 제품은 아니지만 CrowdStrike가 적극적으로 유지 관리하며 오픈 소스 개발자 커뮤니티와 협력하여 지원합니다.

자세한 내용은 SUPPORT 파일을 참조하세요.