MCP Server

Give your AI agents live honeypot threat intelligence

The BlackDome MCP server lets Claude, Cursor, Claude Code, and other MCP-compatible clients query attacker IPs, IOCs, credential previews, payloads, detonation reports, threat actors, and notable attacker sessions directly from BlackDome.

View on PyPIView on GitHub

Run it

Recommended: no install — the client configs below use uvx, which fetches and runs the server on demand. Free public tools work with no API key.

uvx blackdome-mcp

Prefer a fixed install? pip install blackdome-mcp — but if a GUI client says "command not found", it doesn't load your shell PATH: run which blackdome-mcp and paste the full path into the command field instead.

blackdome-mcp
PyPI package, version 0.4.0
io.github.blackdome-ai/blackdome-mcp
MCP server name
stdio + streamable-HTTP
Local package and cloud endpoint
Client Setup

Connect BlackDome to your AI client

Cloud MCP is the one-URL option — no install, works everywhere. Prefer local? Run the package on your machine instead.

Cloud MCP — one URL (recommended)

Paste https://api.blackdome.ai/mcp into any client that supports remote MCP: Claude Desktop, the claude.ai web app, mobile, Cursor. Free tools work without a key; add your key to unlock the paid tier.

{
  "mcpServers": {
    "blackdome-cloud": {
      "url": "https://api.blackdome.ai/mcp",
      "headers": {
        "Authorization": "Bearer bd_your_key_here"
      }
    }
  }
}
Or run it locally

Claude Desktop

Merge this server block into claude_desktop_config.json — ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows — then restart Claude.

{
  "mcpServers": {
    "blackdome": {
      "command": "uvx",
      "args": ["blackdome-mcp"],
      "env": {
        "BLACKDOME_API_KEY": "bd_your_key_here"
      }
    }
  }
}

Claude Code

One command — the key is stored in the MCP config, so there are no shell exports to maintain.

claude mcp add blackdome -e BLACKDOME_API_KEY=bd_your_key_here -- uvx blackdome-mcp

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

{
  "blackdome": {
    "command": "uvx",
    "args": ["blackdome-mcp"],
    "env": {
      "BLACKDOME_API_KEY": "bd_your_key_here"
    }
  }
}
Tools

Free community tools and paid intelligence tools

BlackDome exposes a safe public tier for exploration, then unlocks higher-value intelligence when your API key includes the required plan features.

Free, no API key required

lookup_attacker_ip
top_attackers
attack_map
attack_heatmap
credential_preview
verify_sigil
recent_iocs
ioc_trends
export_iocs as JSON or CSV

Paid feature-gated tools

search_credentials and credential_stats require Credential Intelligence or a candidate Enterprise/OEM pilot (credential_intel or realtime_credential_feed)

list_payloads, get_actor, warboard require the api_access feature

list_detonations, get_detonation_report, and get_artifact require Pro detonation_intel

list_notable_sessions and get_session_transcript require session_intel through a candidate Enterprise/OEM pilot

export_iocs as STIX requires Pro stix_export

explain_ioc requires the Analyst ioc_explanation feature and returns observed evidence

compare_samples requires the Pro sample_compare feature and returns a deterministic comparison

get_evidence_cluster requires the Pro genome_clusters feature and returns a bounded evidence cluster

get_reproducible_novelty requires the Pro reproducible_novelty feature and returns reproducible behavior

get_threatdrop_case and get_takedown_status require ThreatDrop Pro access or a candidate Enterprise pilot; ThreatDrop is a separate product entitlement

whoami requires any valid API key and reports tenant plan, features, scopes, and quota

Environment

Optional runtime variables

You can start with no environment variables. Add a BlackDome API key when you need a key-required tool.

VariableRequiredUse
BLACKDOME_API_KEYNoOptional Bearer API key. Free public tools work without it; paid tools require a key.
BLACKDOME_BASE_URLNoDefaults to https://api.blackdome.ai. Override only for local or private deployments.
BLACKDOME_TIMEOUTNoHTTP request timeout in seconds. Defaults to 15.

API key behavior

Errors are always explicit — a bad key never silently downgrades you to different data.

No key — free community tools work; paid tools return 401.
Invalid key — paid tools fail with 401 Invalid API key. No silent fallback to free-tier results; free tools keep working either way.
Expired key / cancelled plan — 403 with the reason stated.
Wrong plan for a tool — 403. Run whoami to see your plan, features and live quota.
Prompts

Questions your AI client can answer

Ask about attacker behavior, live IOCs, detonation evidence, and paid-session transcripts from the same assistant you already use for security work.

Who are the top attackers hitting the honeypots this month?
Look up attacker IP 176.65.139.56 and summarize what they tried.
Show me the latest malicious sha256 IOCs from the last week.
Render a heatmap of where attacks are coming from.
Export the IOC feed as CSV so I can load it into my SIEM.
What plan am I on and which BlackDome features do I have?
Show me the most active hand-keyed attacker sessions this week.
Pull the detonation report for this sha256 and summarize the behavior and IOCs.
Explain the observed evidence for domain example.test.
Compare these two SHA-256 samples deterministically.
Show the bounded evidence cluster for this IOC.
What reproducible novelty does this URL show?
Show the ThreatDrop case state and takedown workflow status for submission 42.

Need a key for paid intelligence?

Start with the free public tools, then upgrade when your workflow needs credential intelligence, detonation reports, actor clustering, STIX export, or hands-on-keyboard session transcripts.

View PricingAPI Docs