Crow

A local, read-only assistant for your CrowdStrike Falcon tenant.

• Scope: strictly read-only. The API client is scoped so the tool physically cannot mutate your tenant (no contain, no RTR, no incident writes).

• Front-ends: a CLI (cli.py) and an MCP server (server.py) that both wrap the same shared logic in core.py, so they never diverge. The MCP server speaks the standard Model Context Protocol, so any MCP-capable client can use it — Claude Code, Cursor, Zed, any LLM harness or agent that supports MCP — not just one specific tool.

What it can do (v0.2.0, read-only)

Note: detections and incidents are served from the unified Alerts API. CrowdStrike decommissioned the legacy detects endpoint and removed the incidents endpoint (March 2026); incidents are synthesized by grouping related detection alerts that share a control graph.

AI assistant (crow ask)

crow ask "..." translates a natural-language question to the right read-only function, runs it, and summarizes the result with a local Ollama model (LFM2.5-2.6B, e.g. ollama pull hf.co/LiquidAI/LFM2.5-2.6B-GGUF) — no third-party transit. It's available as the crow_ask MCP tool too, so any MCP-capable agent can ask naturally. If Ollama is down or unconfigured it falls back to the raw results with a notice.

See docs/usage.md for full command reference and examples.

Related MCP server: CrowdStrike Falcon MCP Server

Repository layout

Crow/
├── core.py        # shared read-only Falcon logic (falconpy calls)
├── cli.py         # standalone CLI front-end
├── server.py      # MCP server front-end (any MCP-capable client)
├── requirements.txt
├── .env.example   # credential template (copy to .env, chmod 600)
├── .gitignore     # excludes .env and .venv
├── README.md
└── docs/
    ├── usage.md       # command reference + examples
    ├── credentials.md # how to create the read-only API client
    └── architecture.md# how it works / safety model

Quick start

git clone https://github.com/yusif-v/Crow.git
cd Crow
python3 -m venv .venv
./.venv/bin/python -m pip install hatchling wheel setuptools
./.venv/bin/python -m pip install --no-build-isolation "git+https://github.com/CrowdStrike/falconpy.git"
./.venv/bin/python -m pip install "mcp==1.9.4" "python-dotenv>=1.0.0"
cp .env.example .env        # then edit .env with your credentials
chmod 600 .env

Install note: on some networks PyPI returns an empty package list for falconpy (a package filter). Installing it from GitHub source (above) is the workaround. mcp and python-dotenv install normally from PyPI.

Create a read-only Falcon API client (see docs/credentials.md), then:

./.venv/bin/crow detections --severity-min 4

Wiring into an AI client (agent-agnostic)

server.py is a standard MCP server, so it works with any MCP-capable client — Claude Code, Cursor, Zed, your own agent, or any LLM harness that supports the Model Context Protocol. You are not locked into one tool or model.

Example: Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  crow:
    command: "/Users/lizard/Development/Projects/Crow/.venv/bin/python"
    args: ["/Users/lizard/Development/Projects/Crow/server.py"]
    timeout: 120
    connect_timeout: 60

Restart the agent. The crow_* tools then appear and you can ask naturally: "show me critical detections in the last 24 hours".

Example: Claude Code

Claude Code auto-discovers an .mcp.json in the project root. Drop this in ~/Development/Projects/Crow/.mcp.json (or any project where you want Crow available):

{
  "mcpServers": {
    "crow": {
      "command": "/Users/lizard/Development/Projects/Crow/.venv/bin/python",
      "args": ["/Users/lizard/Development/Projects/Crow/server.py"]
    }
  }
}

Or register it globally from the terminal:

claude mcp add crow -- /Users/lizard/Development/Projects/Crow/.venv/bin/python \
  /Users/lizard/Development/Projects/Crow/server.py

Then in Claude Code: /mcp to confirm it connected, and ask naturally.

Example: Codex (OpenAI Codex CLI)

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.crow]
command = "/Users/lizard/Development/Projects/Crow/.venv/bin/python"
args = ["/Users/lizard/Development/Projects/Crow/server.py"]

The crow_* tools are then available to Codex in any session.

Other MCP clients

Any client that reads an MCP server config (stdio transport) can launch server.py the same way — point its command at the venv Python and pass server.py as the argument. The crow_* tools are then available to whatever model that client drives.

Prefer not to run an MCP client at all? Use the CLI (cli.py) directly — same read-only logic, no agent required.

Safety model

• Read-only by construction. The Falcon API client is granted only *:read scopes. No write/contain/RTR scope exists, so the server cannot change state.

• Credentials stay local. Your Client ID / Secret live only in a chmod-600 .env on your machine. They are sent only to CrowdStrike's API. The MCP layer redacts credential-shaped strings from error messages.

• No third-party transit. Queries go directly from your machine to CrowdStrike.

Status

v0.2.0 — read-only visibility across detections, alerts, hosts, incidents, and Falcon X IOC lookups, plus a local AI assistant (crow ask / crow_ask) that maps natural-language questions to the read-only functions and summarizes the results with Ollama. Detections and incidents are backed by the unified Alerts API (CrowdStrike decommissioned the legacy detects and incidents endpoints). List commands paginate automatically past the API page limit; detections/alerts/hosts return rich analyst-friendly summaries (hosts, IPs, users); duplicate hostnames are disambiguated; IOC lookups report missing scope instead of failing cryptically. No caching, no mutating actions. Those are deliberate follow-ups.