osint-mcp

A self-hosted OSINT (Open-Source Intelligence) toolkit that runs five ways: as an MCP server, an interactive AI REPL, a CLI, a web app, and — via OpenClaw — straight from chat apps like WhatsApp, Telegram, and Discord. It bundles 29 investigation tools across three domains — entity intelligence (email, username, breach, domain, IP, phone, geolocation), event / news intelligence (curated news, GDELT events, disasters, humanitarian reporting), and social / community intelligence (engagement-ranked discourse across Reddit, Hacker News, Polymarket, and more) — plus AI-driven multi-target and event investigation.

Keyless-first, not fully keyless: most tools work with no API key, but some sources (breach lookups, Shodan, Censys, and social platforms such as X and Instagram) and the AI agent need optional keys — see Configuration.

For authorized security research, CTF, journalism, and personal digital-footprint auditing only.

Features

• 29 OSINT tools plus AI-driven multi-target and event investigation.
• Three intelligence domains: entity/person-based, event-based (journalist- style) situational awareness, and social/community discourse.
• Event/news intelligence: search ~500 curated news feeds with source-tier and propaganda / state-affiliation flags, GDELT global event coverage, natural- disaster aggregation (USGS / GDACS / NASA EONET), and UN OCHA humanitarian reporting — all keyless.
• Five interfaces from one codebase: MCP server, AI REPL, CLI, web UI, and chat apps (WhatsApp / Telegram / Discord / Slack / …) via OpenClaw.
• Most tools are keyless and work out of the box; API keys are optional and only unlock specific premium sources.
• AI agent powered by Anthropic Claude, DeepSeek (Anthropic-compatible API), or a local Ollama model.
• Optional structured JSON output on every tool.
• Passive-first design: subdomain and certificate discovery never touch the target directly.

Why osint-mcp

| | osint-mcp | theHarvester | SpiderFoot | Maltego CE | | --------------------------------- | :-------: | :----------: | :--------: | :--------: | | MCP-native (drive it from AI agents) | yes | no | no | no | | Interactive AI REPL | yes | no | no | no | | Keyless out of the box | most tools | partial | partial | no | | Event / news intelligence | yes | no | no | no | | Social / community intelligence | yes | no | partial | partial | | CLI + web UI from one codebase | yes | CLI | web | GUI | | License | MIT | GPL | MIT | commercial |

Tools

Entity intelligence

| Tool | Source | API key | | ------------------- | ---------------------------- | ------- | | generate_dorks | built-in | no | | search_email | holehe | no | | search_username | sherlock | no | | search_xposed | XposedOrNot | no | | search_paste | LeakCheck (public) | no | | search_gravatar | Gravatar | no | | search_whois | python-whois | no | | search_dns | dnspython | no | | search_domain | sublist3r | no | | search_crt | crt.sh / certspotter | no | | search_ip | ipinfo.io | optional (IPINFO_TOKEN) | | search_ipgeo | ip-api.com / ipwho.is | no | | search_geocode | Photon / OpenStreetMap | no | | search_phone | phoneinfoga | no | | search_github | GitHub API | optional (GITHUB_TOKEN) | | search_breach | HaveIBeenPwned | yes (HIBP_API_KEY) | | search_ip2location | IP2Location | yes (IP2LOCATION_API_KEY) | | search_abuseipdb | AbuseIPDB | yes (ABUSEIPDB_API_KEY) | | search_shodan | Shodan | yes (SHODAN_API_KEY) | | search_virustotal | VirusTotal | yes (VIRUSTOTAL_API_KEY) | | search_censys | Censys | yes (CENSYS_API_ID + CENSYS_SECRET) | | investigate_multi | full tool chain (AI-driven) | yes (AI provider key) |

Event & news intelligence

| Tool | Source | API key | | ------------------- | --------------------------------- | ------- | | search_news | ~500 curated RSS feeds | no | | search_events | GDELT GKG raw files | no | | search_disasters | USGS / GDACS / NASA EONET | no | | search_reliefweb | ReliefWeb (UN OCHA) | no | | monitor_country | multi-source situational brief | no | | investigate_event | event tool chain (AI-driven) | yes (AI provider key) |

search_news annotates every headline with its source tier (wire / gov / intel / mainstream) and flags state-affiliated or high-propaganda-risk outlets, so corroboration and source bias are visible at a glance.

Social & community intelligence

| Tool | Source | API key | | ------------------- | --------------------------------- | ------- | | search_social | Reddit, Hacker News, Polymarket, GitHub | no (core) |

search_social returns an engagement-ranked, cited brief of what people are actually saying about a topic — ranked by upvotes, comments, and prediction- market money rather than editorial SEO. The keyless core (Reddit, Hacker News, Polymarket, GitHub) works out of the box; setting optional keys (SCRAPECREATORS_API_KEY, BRAVE_API_KEY, OPENROUTER_API_KEY, X/Bluesky credentials) unlocks X/Twitter, TikTok, Instagram, and web search. The bundled engine is the MIT-licensed last30days project (standard-library only, requires Python 3.12+).

Correlation & image GEOINT

| Tool | Source | API key | | ------------------- | --------------------------------------- | ------- | | build_graph | Mermaid + vis-network | no | | geolocate_image | EXIF + GeoCLIP + Picarta + reverse image search | no (core) |

build_graph turns the identifiers found in an investigation into an interactive entity link graph (Mermaid + standalone HTML). geolocate_image estimates where a photo was taken: EXIF GPS is exact when present; otherwise it combines the GeoCLIP image-embedding model (pip install 'osint-mcp[geo]'), an optional Picarta estimate (PICARTA_API_KEY), and reverse-image-search links — all results other than EXIF are clearly labelled as approximate.

Installation

git clone git@github.com:snuri00/osint-mcp.git
cd osint-mcp
pip install -e .

Optional extras:

pip install -e ".[web]"     # web UI dependencies (FastAPI, upload support)
pip install -e ".[geo]"     # photo geolocation — GeoCLIP (pulls PyTorch, large)
pip install -e ".[all]"     # shodan, censys, ollama, pdf, web

The geo extra enables the GeoCLIP image-embedding estimate in geolocate_image. It installs PyTorch (several hundred MB) and downloads the model weights on first run. The keyless core of geolocate_image (EXIF GPS + reverse image search) works without it; set PICARTA_API_KEY to add the optional Picarta photo→GPS estimate.

Some keyless tools shell out to external binaries. Install them once:

pip install holehe sherlock-project sublist3r

After pip install -e . two commands are available: osint-mcp (CLI/REPL) and osint-mcp-server (MCP server over stdio). If you prefer not to install, prefix any command with the project path:

PYTHONPATH=/path/to/osint-mcp python3 -m osint_mcp.cli <command>

Usage

Direct commands (no AI, no key)

osint-mcp dns example.com
osint-mcp email someone@example.com
osint-mcp username johndoe
osint-mcp github torvalds

Interactive AI REPL

export ANTHROPIC_API_KEY=sk-ant-...
osint-mcp

Then type a target or a question at the prompt:

osint-mcp > investigate someone@example.com          # entity intelligence
osint-mcp > what is the latest news on Sudan?         # event intelligence
osint-mcp > monitor Taiwan                             # country situational brief
osint-mcp > investigate the Red Sea shipping disruption

To use DeepSeek (Anthropic-compatible API) instead of Anthropic:

export DEEPSEEK_API_KEY=sk-...
osint-mcp --provider deepseek

To run fully local with no cloud key, use an Ollama model:

osint-mcp --provider ollama

Web app

osint-mcp web

MCP server

The server speaks MCP over stdio. After pip install -e . the osint-mcp-server command is on your PATH; register it with any MCP client.

Claude Code:

claude mcp add osint-mcp -- osint-mcp-server

Other clients (Claude Desktop, etc.) — add to the client's MCP config:

{
  "mcpServers": {
    "osint-mcp": { "command": "osint-mcp-server" }
  }
}

Without installing, run the module form instead — set PYTHONPATH=/path/to/osint-mcp and use python3 -m osint_mcp.mcp_server as the command.

Use from chat apps (OpenClaw)

OpenClaw is a self-hosted gateway that bridges 50+ messaging surfaces (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, …) to an AI agent, and it consumes MCP servers as skills — so all 29 osint-mcp tools become usable straight from a chat. Run OSINT from WhatsApp: "investigate this email", "geolocate this photo", "what's happening in Sudan?".

Register it:

openclaw mcp add osint-mcp --command osint-mcp-server

Or add it to ~/.openclaw/openclaw.json (optional API keys go in env; leave blank for the keyless core). A ready template is in examples/openclaw.json:

{
  "mcp": {
    "servers": {
      "osint-mcp": {
        "command": "osint-mcp-server",
        "env": { "DEEPSEEK_API_KEY": "", "PICARTA_API_KEY": "", "SHODAN_API_KEY": "" }
      }
    }
  }
}

Not installed? Use "command": "python3", "args": ["-m", "osint_mcp.mcp_server"], and "env": { "PYTHONPATH": "/path/to/osint-mcp" }.

It's also published on ClawHub (the OpenClaw skill registry) — install the agent playbook with:

openclaw skills install osint-mcp

The skill source lives in clawhub/SKILL.md. To publish a new version: clawhub skill publish ./clawhub --slug osint-mcp --version <semver> --tags latest.

Configuration

Copy the example environment file and fill in only the keys you need:

cp .env.example .env

The keyless tools work with no configuration. Keys are needed only for the sources marked "yes" in the tables above, and the AI REPL needs one AI provider key — ANTHROPIC_API_KEY or DEEPSEEK_API_KEY — or run it fully local with --provider ollama.

Output format

Each tool accepts an optional json_output flag (MCP) or --json flag (CLI) to return a structured JSON object instead of formatted text, suitable for piping into other tooling.

Disclaimer

This software is provided for lawful, authorized use only: security research, penetration testing with permission, CTF challenges, and auditing your own digital footprint. You are responsible for complying with all applicable laws and the terms of service of every queried provider. Do not use it to target individuals or systems without authorization.

License

MIT.