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

Install

Install the stdio MCP package locally. Free public tools work with no API key.

pip install blackdome-mcp
blackdome-mcp
PyPI package, version 0.2.0
io.github.blackdome-ai/blackdome
MCP server name
stdio
Local package transport
Client Setup

Connect BlackDome to your AI client

The MCP server runs locally and proxies read-only requests to the BlackDome API over HTTPS.

Claude Desktop

Add this server block to your Claude Desktop MCP configuration.

{
  "mcpServers": {
    "blackdome": {
      "command": "blackdome-mcp",
      "env": {
        "BLACKDOME_API_KEY": "bd_your_key_here"
      }
    }
  }
}

Claude Code

Register the server from your shell. Export the key only when you need paid tools.

claude mcp add blackdome -- blackdome-mcp

# Optional, only needed for paid tools:
export BLACKDOME_API_KEY="bd_your_key_here"

Cursor

Add the command to Cursor MCP settings. The environment block is optional.

{
  "blackdome": {
    "command": "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 Enterprise

list_payloads, get_actor, warboard, list_detonations, get_detonation_report, and get_artifact require Pro or higher

list_notable_sessions and get_session_transcript require Enterprise session intelligence

export_iocs as STIX requires Pro or higher

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 Pro or Enterprise tools.

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.
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.

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