LitterBoxMCP
LitterBox ships an MCP (Model Context Protocol) server so an LLM client — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code's MCP extension — can drive uploads, analysis, EDR dispatch, and report generation directly. Same surface as GrumpyCats CLI / GrumpyCats Library, exposed as MCP tools and prompts.
The server lives at GrumpyCats/LitterBoxMCP.py and ships with an installer at GrumpyCats/install_mcp.py.
The installer writes the right mcpServers entry into each client's config and resolves the right Python interpreter automatically (prefers the repo's venv/).
# List supported clients + detection / install status
py GrumpyCats/install_mcp.py --list
# Install into one or more clients
py GrumpyCats/install_mcp.py --install claude-code-project
py GrumpyCats/install_mcp.py --install claude-desktop cursor
py GrumpyCats/install_mcp.py --install all
# Uninstall
py GrumpyCats/install_mcp.py --uninstall cursor
# Just print the JSON entry without touching any files
py GrumpyCats/install_mcp.py --printAfter install, restart the MCP client so it picks up the new server.
| Key | Scope | Config path |
|---|---|---|
claude-code-project |
project | <repo>/.mcp.json |
claude-code-global |
global | ~/.claude.json |
claude-desktop |
global |
%APPDATA%\Claude\claude_desktop_config.json (Win), ~/Library/Application Support/Claude/claude_desktop_config.json (Mac), ~/.config/Claude/... (Linux) |
cursor |
global | ~/.cursor/mcp.json |
windsurf |
global | ~/.codeium/windsurf/mcp_config.json |
vscode-project |
project |
<repo>/.vscode/mcp.json (uses servers key, not mcpServers) |
Aliases: claude-code → claude-code-project, claude → claude-desktop, vscode / vs-code → vscode-project.
The installer is idempotent — re-running it is safe, and uninstall removes only the litterbox entry, leaving any other MCP servers in the file untouched.
Default is stdio (Claude Desktop, Cursor, Claude Code, etc.). For remote use:
py GrumpyCats/LitterBoxMCP.py --transport streamable-http --host 127.0.0.1 --port 8765Logs always go to stderr — stdout is reserved for the JSON-RPC protocol stream and any stray prints there break the connection.
29 tools, organized by domain:
| Tool | Purpose |
|---|---|
upload_payload |
Upload .exe / .dll / .bin / .lnk / .docx / .xlsx
|
upload_driver |
Upload .sys and (default) run BYOVD analysis |
analyze_static |
Run static analysis (YARA / CheckPlz / Stringnalyzer) |
analyze_dynamic |
Run dynamic analysis (memory scanners + RedEdr — executes the payload) |
analyze_holygrail |
Run BYOVD analysis on a driver |
validate_pid |
Confirm a PID exists before targeting it |
| Tool | Purpose |
|---|---|
get_file_info |
Hashes, entropy, PE structure, suspicious imports |
get_static_results |
YARA / CheckPlz / Stringnalyzer findings |
get_dynamic_results |
Memory scanner output + RedEdr telemetry |
get_holygrail_results |
LOLDriver / block status / critical imports |
get_risk_assessment |
Score, level, triggering indicators |
get_comprehensive_results |
Parallel fetch of every saved JSON |
get_report |
Full HTML report inline |
download_report |
Save HTML report to disk |
| Tool | Purpose |
|---|---|
list_edr_profiles |
Profiles registered under Config/edr_profiles/
|
get_edr_agents_status |
Live fleet probe (Whiskers + backend reachability) |
analyze_edr |
Dispatch payload to a profile (Phase 1 + Phase 2 — executes the payload on the EDR VM) |
get_edr_results |
Saved findings for one profile |
get_edr_index |
Cross-profile saved-runs index |
fibratus_alerts_since |
Test the Fibratus alert wire without dispatching a payload |
| Tool | Purpose |
|---|---|
run_blender_scan |
Snapshot the live host as the blender baseline |
compare_with_blender |
Compare a payload against the host snapshot |
analyze_fuzzy_similarity |
ssdeep similarity vs. offensive-tools DB |
create_fuzzy_database |
(Re)build the fuzzy DB from a folder of references |
| Tool | Purpose |
|---|---|
get_scanners_status |
Local analyzer inventory + binary presence |
list_payloads |
Every analyzed payload / driver / process with detection summary |
sandbox_status |
Health, tool readiness, fleet summary |
cleanup_sandbox |
Wipe analysis artifacts (DESTRUCTIVE — confirm first) |
delete_payload |
Delete one payload + its results (DESTRUCTIVE) |
Four OPSEC-review prompts that take a file_hash and return targeted instructions for the LLM:
| Prompt | What it does |
|---|---|
detection_summary |
Summarize what triggered detection, citing rule names and addresses |
evasion_recommendations |
Suggest concrete evasion improvements per detection (with trade-offs) |
attribution_check |
Identify tool / framework attribution risk |
deployment_readiness |
GO / CONDITIONAL / NO-GO verdict against a 4-criterion checklist |
Prompts are short, data-first, and instruct the LLM to load the right tool calls before answering — no padding, no generic categories.
The server hard-codes base_url=http://127.0.0.1:1337 in LitterBoxMCP.py. If you run LitterBox elsewhere, edit that line. (No CLI flag for it because the typical deployment is the MCP client and the LitterBox server on the same host.)
The MCP server itself doesn't authenticate — same trust model as the underlying LitterBox API. Run on a private network only.
FastMCP surfaces tool exceptions to the client automatically. Tools do not wrap returns in {success, error} envelopes — they return the raw API response shape on success and let exceptions propagate on failure. The MCP client (Claude Desktop, etc.) handles the surfacing.
- GrumpyCats CLI — same surface, command-line
- GrumpyCats Library — same surface, Python library (which the MCP server wraps)
- HTTP API Reference — the underlying API
- Model Context Protocol spec — what MCP is
