OpenOSINT MCP Server

mcp-name: io.github.OpenOSINT/openosint

Legal Disclaimer: OpenOSINT is intended for legal and authorized use only. Users are solely responsible for ensuring their use complies with all applicable laws and regulations. The authors accept no liability for misuse. See DISCLAIMER.md.

What is OpenOSINT?

OpenOSINT is an AI agent for Open Source Intelligence with three interfaces: an interactive terminal REPL, a direct CLI, and an MCP server exposable to Claude Code, Claude Desktop, or any MCP-compatible client — plus a browser-based Web UI added in v2.12.0. The AI layer uses Anthropic's native tool use API (or a local Ollama model): the model issues hard stops when it needs a tool, your code executes the real binary, the actual output goes back — hallucination in tool results is structurally impossible.

Features

• AI tool chaining — the agent decides which of 16 tools to run, chains them based on findings, and compiles a structured report
• 16 modular tools covering email, username, breach, WHOIS, IP, subdomain, dorks, paste, phone, Shodan, VirusTotal, Censys, IP2Location, AbuseIPDB, GitHub, and DNS
• Anthropic + Ollama — use Claude via API key or run fully offline with a local Ollama model
• MCP server — expose all tools natively to Claude Code and Claude Desktop
• Parallel execution — --parallel runs complementary tools concurrently via asyncio.gather()
• PDF + Markdown reports — auto-saved after every investigation; PDF export via reportlab
• Session history — all REPL sessions saved to ~/.openosint/history/; browse with openosint history
• Web UI — browser-based AI chat with streaming output, tool cards, and light/dark theme toggle

Installation

# Install from PyPI (recommended)
pip install openosint

# Or install from source
git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .

External binaries (must be in PATH):

Binary	Purpose	Install
holehe	Email account enumeration	pip install holehe
sherlock	Username enumeration (300+ platforms)	pip install sherlock-project
sublist3r	Subdomain enumeration	pip install sublist3r
phoneinfoga	Phone number intelligence	Download binary

If a binary is absent, the corresponding tool returns a descriptive error string. All other tools remain operational.

Quick Start

# Interactive AI REPL (default)
openosint

# Web interface
openosint web

# Direct tool (no AI)
openosint email [email protected]

Configuration

Store all keys in a .env file at the project root (copy .env.example). python-dotenv loads it automatically at startup.

Variable	Tool	Required	Purpose
ANTHROPIC_API_KEY	AI agent	Yes (or use Ollama)	Anthropic API key
HIBP_API_KEY	search_breach	Optional	HaveIBeenPwned v3 — get one
IPINFO_TOKEN	search_ip	Optional	ipinfo.io higher rate limits
SHODAN_API_KEY	search_shodan	Optional	Shodan API — get one
VIRUSTOTAL_API_KEY	search_virustotal	Optional	VirusTotal API v3 — get one
IP2LOCATION_API_KEY	search_ip2location	Optional	IP2Location.io enhanced IP intelligence — get one (sponsored)
CENSYS_API_ID + CENSYS_SECRET	search_censys	Optional	Censys Search API — get one
ABUSEIPDB_API_KEY	search_abuseipdb	Optional	AbuseIPDB v2 — get one
GITHUB_TOKEN	search_github	Optional	GitHub API — raises rate limit from 60 to 5000 req/h — get one

Optional Python packages:

Package	Purpose	Install
ollama	Local LLM backend (no API key)	pip install ollama (Python client only — also install the Ollama runtime)
shodan	Shodan API client	pip install shodan
reportlab	PDF report export	pip install reportlab
censys	Censys API client	pip install censys

Tools

Tool	Powered by	What it investigates
search_email	holehe	Social accounts linked to an email address
search_username	sherlock	Username presence across 300+ platforms
search_breach	HaveIBeenPwned v3 API	Data breach exposure
search_whois	python-whois	Domain registrant and DNS info
search_ip	ipinfo.io	Geolocation, ASN, hostname
search_domain	sublist3r	Subdomain enumeration
generate_dorks	built-in	12 targeted Google dork URLs (no network calls)
search_paste	psbdmp.ws	Pastebin dump mentions
search_phone	phoneinfoga	Carrier, country, line type
search_shodan	Shodan API	Open ports, banners, CVEs
search_virustotal	VirusTotal API v3	Verdict from 70+ antivirus engines
search_ip2location	IP2Location.io API	Enhanced IP intel: VPN/Proxy/Tor/datacenter flags (sponsored)
search_censys	Censys Search API	Internet-facing infrastructure, certificates
search_abuseipdb	AbuseIPDB v2 API	IP abuse reputation: confidence score, reports, country, ISP
search_github	GitHub REST API	Profile, repos, commit-discovered emails, username/keyword search
search_dns	dnspython (built-in)	A/AAAA/MX/NS/TXT/CNAME/SOA records; SPF, DMARC, DKIM analysis

search_email

Enumerates online services linked to an email address using holehe.

openosint email [email protected]
openosint email [email protected] -t 60

OSINT results for '[email protected]':
[+] Spotify        https://open.spotify.com/user/target
[+] WordPress      https://wordpress.com/target
[+] Gravatar       https://gravatar.com/target
[+] Office365      email used

search_username

Searches for a username across 300+ platforms using sherlock.

openosint username johndoe99
openosint username johndoe99 -t 120

OSINT results for username 'johndoe99':
[+] GitHub         https://github.com/johndoe99
[+] Twitter        https://twitter.com/johndoe99
[+] Reddit         https://reddit.com/user/johndoe99

search_breach

Checks data breach exposure via HaveIBeenPwned v3 API. Requires HIBP_API_KEY.

Found in 2 breach(es) for '[email protected]':
[+] LinkedIn (2016-05-05) — leaked: Email addresses, Passwords
[+] Adobe (2013-10-04) — leaked: Email addresses, Password hints

search_whois

Retrieves WHOIS data for a domain using python-whois.

WHOIS results for 'example.com':
[+] Registrar: ICANN
[+] Created: 1995-08-14
[+] Expires: 2024-08-13
[+] Name Servers: A.IANA-SERVERS.NET

search_ip

Retrieves geolocation and ASN data via ipinfo.io. Free tier: 50k/month.

IP intelligence for '8.8.8.8':
[+] Hostname: dns.google
[+] Org: AS15169 Google LLC
[+] City: Mountain View, CA, US

search_domain

Enumerates subdomains using sublist3r.

Subdomains found for 'example.com':
[+] mail.example.com
[+] dev.example.com
[+] api.example.com

generate_dorks

Generates 12 targeted Google dork URLs for any target. No network calls.

Google dork URLs for 'johndoe':
[+] "johndoe" site:linkedin.com
    https://www.google.com/search?q=%22johndoe%22+site%3Alinkedin.com
[+] "johndoe" leaked OR breach OR dump
    https://www.google.com/search?q=%22johndoe%22+leaked+OR+breach+OR+dump

search_paste

Searches Pastebin dumps via psbdmp.ws.

Found in 3 paste(s) for '[email protected]':
[+] https://pastebin.com/aB1cD2eF (2023-04-12)
[+] https://pastebin.com/xY3zA4bC (2022-11-08)

search_phone

Gathers phone intelligence using phoneinfoga. Use E.164 format.

Phone intelligence for '+14155552671':
[+] Country: United States
[+] Carrier: AT&T
[+] Line type: Mobile

search_shodan

Queries the Shodan API. IPv4 input → host lookup (open ports, org, CVEs). Any other query → banner/keyword search. Requires SHODAN_API_KEY.

openosint shodan 8.8.8.8
openosint shodan "apache port:80 country:DE"
openosint shodan 8.8.8.8 -t 30

Shodan host intelligence for '8.8.8.8':
[+] IP: 8.8.8.8
[+] Org: Google LLC
[+] Country: United States
[+] Open ports: 53, 443

search_virustotal

Checks an IP address, domain, URL, or file hash against VirusTotal's 70+ antivirus engines using API v3. Auto-detects input type. Requires VIRUSTOTAL_API_KEY.

openosint virustotal 8.8.8.8
openosint virustotal example.com
openosint virustotal https://example.com/path
openosint virustotal 44d88612fea8a8f36de82e1278abb02f

[VirusTotal] Type: ip
[VirusTotal] ASN: AS15169 Google LLC
[VirusTotal] Malicious: 0
[VirusTotal] Harmless: 72

If any engine flags the target:

[VirusTotal] Malicious: 3
FLAGGED AS MALICIOUS by 3 engines

search_censys

Queries the Censys API. IPv4 input → host view (open ports, services, ASN); domain input → certificate search (SANs, issuer, first/last seen). Requires CENSYS_API_ID and CENSYS_SECRET.

openosint censys 8.8.8.8
openosint censys example.com

[Censys] IP: 8.8.8.8
[Censys] Open Ports: 53, 443, 853
[Censys] Services: DNS, HTTPS, DNS-over-TLS
[Censys] ASN: AS15169 Google LLC
[Censys] Country: United States

[Censys] Domain: example.com
[Censys] Certificates Found: 12
[Censys] Issuer: Let's Encrypt
[Censys] SANs: example.com, www.example.com, api.example.com

search_ip2location

Queries the IP2Location.io API for enhanced IP intelligence: geolocation (country, region, city, coordinates, ZIP), ISP, domain, ASN, and — on the Security Plan — VPN, proxy, Tor exit node, and datacenter detection. Sponsored integration. Requires IP2LOCATION_API_KEY.

openosint ip2location 8.8.8.8
openosint ip2location 2001:4860:4860::8888

[IP2Location] IP: 8.8.8.8
[IP2Location] Country: United States (US)
[IP2Location] Region: California
[IP2Location] City: Mountain View
[IP2Location] ISP: Google LLC
[IP2Location] ASN: AS15169 Google LLC
[IP2Location] VPN: No  |  Proxy: No  |  TOR: No  |  Datacenter: Yes
[IP2Location] Threat: clean

If a VPN, proxy, or Tor exit node is detected:

FLAGGED: VPN/Proxy/Tor detected

search_abuseipdb

Checks an IP address against the AbuseIPDB v2 API for abuse reputation. Returns abuse confidence score (0–100%), total reports, country, ISP, domain, and last reported timestamp. Requires ABUSEIPDB_API_KEY.

openosint abuseipdb 198.51.100.1
openosint abuseipdb 198.51.100.1 -t 30

Abuse intelligence for '198.51.100.1':

[AbuseIPDB] IP: 198.51.100.1
[AbuseIPDB] Abuse Confidence Score: 87%
[AbuseIPDB] Total Reports: 143
[AbuseIPDB] Country: US
[AbuseIPDB] ISP: Example ISP LLC
[AbuseIPDB] Domain: example-isp.net
[AbuseIPDB] Last Reported: 2026-05-20T14:33:00+00:00
⚠️  HIGH ABUSE CONFIDENCE — flagged by AbuseIPDB

The warning line only appears when abuseConfidenceScore exceeds 50%.

Interfaces

Interactive REPL

Run openosint with no arguments to start the AI-powered REPL:

openosint > investigate [email protected]

  -> generate_dorks('[email protected]')
  -> search_email('[email protected]')
  Found: Spotify, WordPress, Gravatar, Office365

  -> search_breach('[email protected]')
  Found in 2 breaches: LinkedIn (2016), Adobe (2013)

  Report saved -> reports/2026-05-11_14-32-11_report.md

REPL commands:

Command	Description
<target>	Investigate any target — email, username, domain, IP, name
clear	Reset conversation memory
save	Save last report to reports/
tools	List available tools and their status
config	Show current configuration
history	Browse saved sessions
help	Show all commands
exit / Ctrl-D	Exit

All sessions are auto-saved to ~/.openosint/history/. Browse with openosint history.

Web UI

Introduced in v2.12.0:

openosint web
# Opens http://localhost:8080 automatically

Browser-based AI chat interface with streaming tool output, inline result cards, light/dark theme toggle, and Ollama support for fully local inference. No API key required when using Ollama.

# Install web extras
pip install "openosint[web]"
openosint web

# Use Ollama for fully local inference (no API key)
# Step 1: install the Ollama runtime (separate from the Python library)
#   macOS/Linux:  curl -fsSL https://ollama.com/install.sh | sh
#   Windows:      https://ollama.com/download/windows
# Step 2: start Ollama and pull a model
ollama serve          # start in a terminal (runs automatically as a service on some platforms)
ollama pull llama3.2  # download the model (~2 GB)
# Step 3: launch OpenOSINT and switch to Ollama
openosint web
# Settings -> Ollama (local) -> set model to llama3.2

MCP Server

Expose all 16 OpenOSINT tools to any MCP-compatible AI client. Once connected, Claude can natively invoke all 16 tools during conversations.

Claude Code:

claude mcp add openosint python /absolute/path/to/OpenOSINT/openosint/mcp_server.py
claude mcp list

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openosint": {
      "command": "python",
      "args": ["/absolute/path/to/OpenOSINT/openosint/mcp_server.py"]
    }
  }
}

Agentic use via Claude Code:

$ claude
> Investigate [email protected]. Trace any username found
  across other platforms and compile a full report.

Docker

# Build and run
docker compose up --build

# One-off command
docker compose run --rm openosint email [email protected] --json

Set ANTHROPIC_API_KEY (and optionally HIBP_API_KEY, IPINFO_TOKEN) in a .env file or export them before running docker compose. Reports are persisted to ./reports/ via a volume mount.

DigitalOcean App Platform: see .do/app.yaml for App Platform configuration.

CLI Reference

Flag / Subcommand	Description
openosint	Interactive AI REPL (default)
openosint web [--port N] [--no-browser]	Launch browser UI
openosint email ADDRESS [-t N]	Direct email scan
openosint username HANDLE [-t N]	Direct username scan
openosint shodan QUERY [-t N]	Shodan lookup
openosint virustotal TARGET [-t N]	VirusTotal lookup
openosint censys TARGET [-t N]	Censys lookup
openosint ip2location IP [-t N]	IP2Location lookup
openosint abuseipdb IP [-t N]	AbuseIPDB reputation check
openosint github QUERY [-t N]	GitHub profile/repo/email discovery
openosint dns DOMAIN [-t N]	DNS records + email security analysis
openosint multi TARGETS	Parallel multi-target investigation (max 10)
openosint history [--all] [open N] [clear]	View/manage REPL session history
-v, --verbose	Enable debug logging to stderr
-t, --timeout N	Override subprocess timeout (seconds)
--api-key KEY	Anthropic API key (overrides env var)
--parallel	Run complementary tools concurrently
--json	Output results as structured JSON
--provider {anthropic,ollama}	AI provider (default: anthropic)
--ollama-model MODEL	Ollama model name (default: llama3.2)
--ollama-host URL	Ollama server URL (default: http://localhost:11434)
--no-pdf	Disable automatic PDF generation

Integrations

Service	URL	Tool	Tier	Auth
IP2Location.io	https://www.ip2location.io	search_ip2location	Featured (sponsored)	API key — free tier
AbuseIPDB	https://www.abuseipdb.com	search_abuseipdb	Community	API key — free tier
Censys	https://censys.io	search_censys	Community	API key — free tier
GitHub	https://github.com	search_github	Community	Token optional
HaveIBeenPwned	https://haveibeenpwned.com	search_breach	Community	API key — paid
holehe	https://github.com/megadose/holehe	search_email	Community	None — local binary
ipinfo.io	https://ipinfo.io	search_ip	Community	Token optional
phoneinfoga	https://github.com/sundowndev/phoneinfoga	search_phone	Community	None — local binary
psbdmp.ws	https://psbdmp.ws	search_paste	Community	None
sherlock	https://github.com/sherlock-project/sherlock	search_username	Community	None — local binary
Shodan	https://shodan.io	search_shodan	Community	API key — free tier
sublist3r	https://github.com/aboul3la/Sublist3r	search_domain	Community	None — local binary
VirusTotal	https://www.virustotal.com	search_virustotal	Community	API key — free tier
WHOIS (IANA)	https://www.iana.org/whois	search_whois	Community	None
DNS (system resolver)	—	search_dns	Community	None
Google Search	https://www.google.com	generate_dorks	Community	None

Sponsor this project

OpenOSINT is used by OSINT practitioners, security researchers, and developers who are actively evaluating and adopting intelligence APIs. Every time a user configures a new integration, the documentation routes them directly to that provider's sign-up page — putting sponsors in front of their target audience at the moment of adoption.

Sponsorship tiers

Tier	Benefits
Featured Integration	Recommended/default provider for a tool category; logo + badge in README, website, and docs; "Featured (sponsored)" label in the Integrations table; listed first among providers for that category
Sponsor	Logo + link in README, website, and release notes
Supporter	Listed on the website sponsors page

Featured Integration tiers are available — contribute via Open Collective or email [email protected] for current rates and custom arrangements.

Community integrations in the table above are eligible to upgrade to a Featured Integration sponsorship.

Current sponsors

IP2Location.io — Featured Integration sponsor for the IP geolocation and threat intelligence category. Powers the search_ip2location tool with VPN, proxy, Tor exit node, and datacenter detection.

---

To sponsor OpenOSINT: Open Collective · email [email protected] · full prospectus: SPONSORS.md.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow, integration registration checklist, and coding conventions. Please read DISCLAIMER.md before contributing.

Maintainer

Tommaso Bertocchi

• X (personal): https://x.com/SonoTommy_
• X (OpenOSINT): https://x.com/openosint_oss
• LinkedIn: https://www.linkedin.com/company/openosintoss
• Email: [email protected]

Contributors

Contributor	Contribution
@consocio	venv/uv-tool binary resolution fix — co-installed tools are now found without a separate activation step (#6)

License

OpenOSINT is open source under the MIT License — free for personal, academic, and open source use.

For commercial use in closed-source products, a separate license is required. → Full details

---

For authorized security research only. See DISCLAIMER.md.

OpenOSINT v2.18.1 — June 2, 2026

Star History