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-mcpThen 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 deepseekTo run fully local with no cloud key, use an Ollama model:
osint-mcp --provider ollama
Web app
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:
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.
Responsible use
osint-mcp aggregates public sources, but the techniques are dual-use — especially the individual-targeting ones (photo geolocation, breach lookups, account enumeration). Use it only for authorized, lawful purposes: security research, pentesting with permission, CTF, journalism in the public interest, and auditing your own footprint.
Do not use it to stalk, dox, surveil, locate, harass, or harm a specific person without their consent, to target people/systems you aren't authorized to assess, or to violate any law, privacy regulation, or provider terms of service.
Results are often estimates (geolocation, AI inference, breach matching) and can be wrong — never treat an estimate as fact or act against someone based on an unverified result. When deploying via bots/chat (OpenClaw, ClawHub), the operator must keep the same boundaries and add guardrails for sensitive features. The AI agent declines requests whose evident purpose is to harm or surveil a private individual.
See CODE_OF_CONDUCT.md for the full acceptable-use policy. You are responsible for your use and for complying with all applicable laws.
License
MIT.