The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the BlackDome Threat Intel listing page.
Give your AI agents direct access to live honeypot threat intelligence. Look up attacker IPs, browse indicators of compromise (IOCs), inspect captured credentials and malware payloads, profile threat actors, and render a real-time global attack map — all from Claude, Cursor, or any MCP-compatible client.
Most tools are free and need no API key (the public community tier). A subset of high-value intelligence requires a paid plan.
One URL, works in every client that supports remote MCP (Claude Desktop, the claude.ai web app, mobile, Cursor):
Free tools work with no key. To unlock the paid tiers (credential intelligence, payloads, actors, warboard, STIX export), get an API key at https://blackdome.ai/pricing and add it as an Authorization header:
Use uvx (part of uv) — it fetches and runs the server on demand, with no separate install step and no PATH issues:
Prefer a fixed install? pip install blackdome-mcp works too — but note the troubleshooting item at the bottom if your client says "command not found".
The free public tools work with no API key. To unlock the paid tiers, get a key at https://blackdome.ai/pricing.
Merge this into claude_desktop_config.json — ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows — then restart Claude:
The
envblock is optional — omitBLACKDOME_API_KEYto run free public tools only.
One command — the key is stored in the MCP config, so there are no shell exports to maintain (a plain export BLACKDOME_API_KEY=... only lasts for that terminal session, and your paid tools would stop working in the next one):
For free tools only:
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):
401.whoami) fail loudly with 401 Invalid API key — there is no silent fallback to free-tier results. Free tools keep working regardless of key validity.403 API key has expired / 403 Tenant account is inactive — again explicit errors, not degraded data.403; check your granted features any time with whoami.If a paid tool returns less than expected, run whoami first — it reports your plan, features, and live quota.
Free tools work with no key. Paid tools require an API key whose plan includes the listed feature.
| Tool | Tier | Description |
|---|---|---|
lookup_attacker_ip | Free | Full dossier for one attacker IP — events, protocols, credentials (passwords masked), MITRE, edge nodes |
top_attackers | Free | Most active attacker IPs over a window — pick one to drill into |
attack_map | Free | Recent geolocated attack events for a live map (limit ≥ 10) |
attack_heatmap | Free | Country-aggregated attack heatmap with centroids (limit ≥ 5) |
credential_preview | Free | Sample of recent credentials (masked server-side) + teaser totals |
verify_sigil | Free | Verify a BlackDome Sigil / audit record by id |
recent_iocs | Free | Browse recent redacted IOCs — type/severity filters (72h community delay, 25-row cap) |
ioc_trends | Free | Aggregated IOC trends — totals, breakdowns, daily new, top MITRE |
export_iocs | Free (json/csv) · Pro (stix) | Export the IOC feed; STIX bundle needs the stix_export feature |
search_credentials | Enterprise (credential_intel) | Search the global credential corpus with PLAINTEXT passwords |
credential_stats | Enterprise (credential_intel) | Aggregate credential stats — top usernames/passwords, breakdowns |
list_payloads | Pro (api_access) | List captured malware payloads, or fetch one by sha256 (VT/MB intel) |
get_actor | Pro (api_access) | List clustered threat actors, or fetch one actor's sessions |
warboard | Pro (api_access) | Sigil leaderboard with intrusion narratives + attacker command tails |
list_notable_sessions | Enterprise (session_intel) | Ranked hand-keyed attacker sessions surfaced out of botnet noise |
get_session_transcript | Enterprise (session_intel) | Structured command/output transcript for one attacker session |
list_detonations | Pro (detonation_intel) | Malware detonation list with verdicts, Magika labels and IOC counts |
get_detonation_report | Pro (detonation_intel) | Full detonation report with behavior, IOCs, artifact classification and report availability |
get_artifact | Pro (detonation_intel) | Artifact dossier with linked detonation, IOCs and session identifiers only |
whoami | Any key | Check your tenant, plan, features and live quota |
Plans: Community (free) → Analyst ($49, real-time intel) → Pro ($299, adds stix_export, api_access, detonation_intel) → Enterprise ($2000, adds credential_intel, bulk_api, session_intel) → OEM ($5000). See pricing.
Once connected, try asking your AI assistant:
whoami)Local (stdio) server only — the cloud endpoint takes the key as an Authorization: Bearer header instead.
| Variable | Required | Default | Description |
|---|---|---|---|
BLACKDOME_API_KEY | No | — | Bearer API key. Free tools work without it; paid tools require it |
BLACKDOME_BASE_URL | No | https://api.blackdome.ai | API base URL |
BLACKDOME_TIMEOUT | No | 15 | Request timeout in seconds |
The free community tier is capped at roughly 30 requests/minute and 100 requests/day, and community IOC data carries a 72-hour freshness delay. Paid plans raise these limits substantially (Enterprise: 1000 req/min, 50,000 req/day). When you hit a limit the server returns a clear 429 error with retry timing. Use whoami to see your live quota.
"command": "uvx", "args": ["blackdome-mcp"] as shown above. If you pip-installed instead, run which blackdome-mcp (macOS/Linux) or where blackdome-mcp (Windows) and paste the full path into the command field.whoami tells you exactly what your key grants.lookup_attacker_ip tool masks captured passwords to ******** before returning them; credential_preview is masked server-side. Plaintext passwords are returned only by the paid search_credentials tool, which requires the credential_intel feature.MIT