Eidolon

Eidolon is a privacy-first approach to finding and understanding your digital footprint. The stack uses OSINT tools to gather information based on your search parameters, then a local LLM compiles it into a report. The LLM runs on your machine, so no data ever reaches an external service or leaves your box — you own your data.

What it does

• Aggregates ~25 OSINT sources — breaches, leaked credentials, data brokers, account enumeration, public records, phone/email intel, exposed hosts — into a single risk report.
• Maps findings to MITRE ATT&CK so you see what an attacker could actually do with what's exposed.
• Flags AI-training exposure (which platforms may train on your data, and how to opt out).
• Risk scoring and the leaked-credential dossier are deterministic — built from scan state, not the LLM — so the report survives an LLM hiccup. The model only writes narrative.
• Outputs Markdown, PDF, and JSON.

MCP-native

Eidolon runs as an MCP server, so you can drive it from any MCP client (Claude Desktop, Claude Code) — scan a target, list past scans, and read reports conversationally. It runs locally over stdio; your data never leaves the box.

Tools: scan_target, scan_status, list_scans, get_report, reveal_credentials. A scan takes minutes, so scan_target returns a scan_id immediately and runs in the background — poll scan_status(scan_id) until it reports done, then get_report(scan_id). The leaked-credential dossier (plaintext passwords from breach dumps) is redacted by default and only returned when you explicitly call reveal_credentials.

Requirements

Everything below is optional — Eidolon runs with whatever you give it and tells you, per source, what it couldn't check (no token) versus what it checked and found nothing.

• Python 3.11+ and uv (required)
• Ollama for the local LLM narrative: ollama pull llama3.1:8b — if it's down, the report is still produced deterministically (just no written narrative).
• A running SpiderFoot instance — skipped if unreachable.
• API keys — see .env.example. Each unlocks one data source and skips cleanly if absent (the report says "not checked — set X"). A scan with no keys is sparse but still runs.

New here? Start with the Setup & Configuration guide — which keys to get, what each one costs, and what it unlocks.

Quickstart

git clone https://github.com/sudohnim/eidolon && cd eidolon
uv sync
cp .env.example .env        # fill in your keys

# scan yourself from the CLI
uv run eidolon --email you@example.com

# or run the MCP server (stdio)
uv run eidolon-mcp

Use from Claude Desktop

Option 1 — from a local clone (loads .env from cwd):

{
  "mcpServers": {
    "eidolon": {
      "command": "uv",
      "args": ["run", "eidolon-mcp"],
      "cwd": "/absolute/path/to/eidolon"
    }
  }
}

Option 2 — from PyPI via uvx (recommended, no clone needed). Pass your keys in the env block:

{
  "mcpServers": {
    "eidolon": {
      "command": "uvx",
      "args": ["--from", "eidolon-osint", "eidolon-mcp"],
      "env": {
        "HIBP_API_KEY": "...",
        "DEHASHED_API_KEY": "...",
        "OLLAMA_HOST": "http://localhost:11434"
      }
    }
  }
}

Option 3 — straight from GitHub (pre-release / latest commit):

{
  "mcpServers": {
    "eidolon": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sudohnim/eidolon", "eidolon-mcp"],
      "env": {
        "HIBP_API_KEY": "...",
        "DEHASHED_API_KEY": "...",
        "OLLAMA_HOST": "http://localhost:11434"
      }
    }
  }
}

Add only the keys you have — the rest skip cleanly. Then ask Claude to "scan my email"; it c

... View full README on GitHub