{
  "markdown": "<!-- mcp-name: io.github.blackdome-ai/blackdome-mcp -->\n\n# BlackDome MCP Server\n\nGive 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.\n\nMost tools are **free and need no API key** (the public community tier). A subset of high-value intelligence requires a paid plan.\n\n## Quick Start\n\n### Option 1 — Cloud MCP (recommended, no install)\n\nOne URL, works in every client that supports remote MCP (Claude Desktop, the claude.ai web app, mobile, Cursor):\n\n```\nhttps://api.blackdome.ai/mcp\n```\n\nFree 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](https://blackdome.ai/pricing)** and add it as an `Authorization` header:\n\n```json\n{\n  \"mcpServers\": {\n    \"blackdome-cloud\": {\n      \"url\": \"https://api.blackdome.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer bd_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Option 2 — Run it locally\n\nUse `uvx` (part of [uv](https://docs.astral.sh/uv/)) — it fetches and runs the server on demand, with no separate install step and no PATH issues:\n\n```bash\nuvx blackdome-mcp\n```\n\nPrefer a fixed install? `pip install blackdome-mcp` works too — but note the troubleshooting item at the bottom if your client says \"command not found\".\n\nThe free public tools work with **no API key**. To unlock the paid tiers, get a key at **[https://blackdome.ai/pricing](https://blackdome.ai/pricing)**.\n\n#### Claude Desktop\n\nMerge this into `claude_desktop_config.json` — `~/Library/Application Support/Claude/` on macOS, `%APPDATA%\\Claude\\` on Windows — then restart Claude:\n\n```json\n{\n  \"mcpServers\": {\n    \"blackdome\": {\n      \"command\": \"uvx\",\n      \"args\": [\"blackdome-mcp\"],\n      \"env\": {\n        \"BLACKDOME_API_KEY\": \"bd_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n> The `env` block is optional — omit `BLACKDOME_API_KEY` to run free public tools only.\n\n#### Claude Code\n\nOne 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):\n\n```bash\nclaude mcp add blackdome -e BLACKDOME_API_KEY=bd_your_key_here -- uvx blackdome-mcp\n```\n\nFor free tools only:\n\n```bash\nclaude mcp add blackdome -- uvx blackdome-mcp\n```\n\n#### Cursor\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):\n\n```json\n{\n  \"blackdome\": {\n    \"command\": \"uvx\",\n    \"args\": [\"blackdome-mcp\"],\n    \"env\": {\n      \"BLACKDOME_API_KEY\": \"bd_your_key_here\"\n    }\n  }\n}\n```\n\n## API Key Behavior\n\n- **No key:** free community tools work; paid tools return an explicit `401`.\n- **Invalid key:** paid tools (and `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.\n- **Expired key / cancelled plan:** `403 API key has expired` / `403 Tenant account is inactive` — again explicit errors, not degraded data.\n- **Valid key, wrong plan:** a tool whose feature your plan does not include returns an explicit `403`; check your granted features any time with `whoami`.\n\nIf a paid tool returns less than expected, run `whoami` first — it reports your plan, features, and live quota.\n\n## Available Tools\n\nFree tools work with no key. Paid tools require an API key whose plan includes the listed feature.\n\n| Tool | Tier | Description |\n|------|------|-------------|\n| `lookup_attacker_ip` | **Free** | Full dossier for one attacker IP — events, protocols, credentials (passwords masked), MITRE, edge nodes |\n| `top_attackers` | **Free** | Most active attacker IPs over a window — pick one to drill into |\n| `attack_map` | **Free** | Recent geolocated attack events for a live map (limit ≥ 10) |\n| `attack_heatmap` | **Free** | Country-aggregated attack heatmap with centroids (limit ≥ 5) |\n| `credential_preview` | **Free** | Sample of recent credentials (masked server-side) + teaser totals |\n| `verify_sigil` | **Free** | Verify a BlackDome Sigil / audit record by id |\n| `recent_iocs` | **Free** | Browse recent redacted IOCs — type/severity filters (72h community delay, 25-row cap) |\n| `ioc_trends` | **Free** | Aggregated IOC trends — totals, breakdowns, daily new, top MITRE |\n| `export_iocs` | **Free** (json/csv) · **Pro** (stix) | Export the IOC feed; STIX bundle needs the `stix_export` feature |\n| `search_credentials` | **Enterprise** (`credential_intel`) | Search the global credential corpus with PLAINTEXT passwords |\n| `credential_stats` | **Enterprise** (`credential_intel`) | Aggregate credential stats — top usernames/passwords, breakdowns |\n| `list_payloads` | **Pro** (`api_access`) | List captured malware payloads, or fetch one by sha256 (VT/MB intel) |\n| `get_actor` | **Pro** (`api_access`) | List clustered threat actors, or fetch one actor's sessions |\n| `warboard` | **Pro** (`api_access`) | Sigil leaderboard with intrusion narratives + attacker command tails |\n| `list_notable_sessions` | **Enterprise** (`session_intel`) | Ranked hand-keyed attacker sessions surfaced out of botnet noise |\n| `get_session_transcript` | **Enterprise** (`session_intel`) | Structured command/output transcript for one attacker session |\n| `list_detonations` | **Pro** (`detonation_intel`) | Malware detonation list with verdicts, Magika labels and IOC counts |\n| `get_detonation_report` | **Pro** (`detonation_intel`) | Full detonation report with behavior, IOCs, artifact classification and report availability |\n| `get_artifact` | **Pro** (`detonation_intel`) | Artifact dossier with linked detonation, IOCs and session identifiers only |\n| `whoami` | **Any key** | Check your tenant, plan, features and live quota |\n\n**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](https://blackdome.ai/pricing).\n\n## Example Prompts\n\nOnce connected, try asking your AI assistant:\n\n- *\"Who are the top attackers hitting the honeypots this month?\"*\n- *\"Look up attacker IP 176.65.139.56 and summarize what they tried.\"*\n- *\"Show me the latest malicious sha256 IOCs from the last week.\"*\n- *\"What are the IOC trends — which MITRE techniques are spiking?\"*\n- *\"Render a heatmap of where attacks are coming from.\"*\n- *\"Export the IOC feed as CSV so I can load it into my SIEM.\"*\n- *\"What plan am I on and which features do I have?\"* (runs `whoami`)\n- *\"Search captured SSH credentials for the username root.\"* (paid)\n- *\"Show me the most active hand-keyed attacker sessions this week.\"* (Enterprise)\n- *\"Pull the detonation report for sha256 a6713518f2e26745683d33ded61b465d0645d7af850464c559fba8bb84e68398.\"* (Pro)\n\n## Environment Variables\n\nLocal (stdio) server only — the cloud endpoint takes the key as an `Authorization: Bearer` header instead.\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BLACKDOME_API_KEY` | No | — | Bearer API key. Free tools work without it; paid tools require it |\n| `BLACKDOME_BASE_URL` | No | `https://api.blackdome.ai` | API base URL |\n| `BLACKDOME_TIMEOUT` | No | `15` | Request timeout in seconds |\n\n## Rate Limits\n\nThe 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.\n\n## Troubleshooting\n\n- **\"command not found\" in a GUI client:** GUI apps don't load your shell PATH. Easiest fix: use `\"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.\n- **Paid tools return 401/403:** see [API Key Behavior](#api-key-behavior) — errors are explicit, and `whoami` tells you exactly what your key grants.\n\n## Security\n\n- **Read-only.** Every tool is a GET request — the server never mutates BlackDome data.\n- **Keyless free tier.** Public tools require no API key and expose only community-tier data.\n- **Masked credentials.** The free `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.\n- **Secrets stay local.** Your API key is read from the environment and sent only to the BlackDome API over HTTPS. No data is stored by the MCP server — it proxies directly to BlackDome.\n\n## License\n\nMIT\n",
  "bytes": 9064,
  "sha": "55b61779aab9a9fe8336b05f163b84caeaa1180a75a89aac8ca6fa101273f1ed",
  "repo_slug": "blackdome-ai/blackdome-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_blackdome_ai_blackdome_b1650ef0/readme"
}