openosint — AI-powered OSINT agent, MCP server, and CLI for Open Source Intelligence

openosint                          # interactive AI REPL (default)
openosint shell                    # same as above
openosint email address [-t seconds]  # direct scan, no AI
openosint username handle [-t seconds] # direct scan, no AI
openosint ip2location address [-t seconds]   # IP2Location lookup
openosint abuseipdb address [-t seconds]    # AbuseIPDB reputation check
openosint [-v] [--api-key key]

openosint is a modular OSINT framework with three interfaces:

Interactive REPL (default) — a Claude Code-style terminal where you type targets or questions in natural language. The AI agent decides which tools to run, chains them based on findings, and compiles a structured report.

Direct CLI — run individual OSINT tools without AI for scripting or quick lookups.

MCP Server — expose all 14 tools to any MCP-compatible AI client (Claude Code, Claude Desktop).

The AI layer uses the Anthropic native tool use API. The model issues hard stops when it needs a tool — the real tool executes and real output goes back. Hallucination in tool results is structurally impossible.

Layer	Path	Responsibility
Core tools	openosint/tools/	Async wrappers around external OSINT binaries and APIs. Stateless.
AI agent	openosint/agent.py	Anthropic tool use loop. Maintains conversation history per session.
REPL	openosint/repl.py	Interactive terminal session. prompt_toolkit + Rich.
MCP server	openosint/mcp_server.py	MCP tool schema exposure for external AI clients.
CLI	openosint/cli.py	Entry point. Launches REPL or direct commands.

No layer imports from a layer above it.

Requires Python 3.10 or later.

$ git clone https://github.com/OpenOSINT/OpenOSINT.git
$ cd OpenOSINT
$ pip install -e .
$ export ANTHROPIC_API_KEY=sk-ant-...

External dependencies (must be present 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. All other tools remain operational.

Optional environment variables:

Variable	Tool	Purpose
HIBP_API_KEY	search_breach	HaveIBeenPwned API key — get one here
IPINFO_TOKEN	search_ip	ipinfo.io token for higher rate limits
IP2LOCATION_API_KEY	search_ip2location	IP2Location API key — get one here
ABUSEIPDB_API_KEY	search_abuseipdb	AbuseIPDB API key — get one here

A browser-based AI chat interface for all OSINT tools with real-time streaming output, tool result cards, and light/dark theme.

Local

pip install "openosint[web]"
openosint web

Opens automatically at http://localhost:8080

Features

• AI chat interface with tool results inline
• Light/dark theme toggle (preference saved in browser)
• Full conversation history per session
• Ollama support for local inference (no API key required)
• API key management via Settings modal

Hosted version

A hosted version at openosint.tech/app is coming soon. COMING SOON
Currently the web interface runs locally only.

Run openosint with no arguments to start the AI-powered REPL. Type targets or questions in natural language.

openosint ❯ investigate target@example.com

  → generate_dorks('target@example.com')
  → search_email('target@example.com')
  ✓ Found: Spotify, WordPress, Gravatar, Office365

  → search_breach('target@example.com')
  ✓ Found in 2 breaches: LinkedIn (2016), Adobe (2013)

  ╭──────────────── Report ────────────────╮
  │ ## Summary                             │
  │ Single target — high confidence.       │
  │                                        │
  │ ## Online Presence                     │
  │ Spotify · WordPress · Gravatar         │
  │                                        │
  │ ## Data Breaches                       │
  │ LinkedIn (2016) · Adobe (2013)         │
  ╰────────────────────────────────────────╯

  ✓ Report saved → reports/2026-05-11_report.md

REPL commands:

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

Reports are auto-saved after every investigation containing structured findings.

Quick reference:

Tool	Method	What it finds
search_email	holehe	Social accounts linked to an email
search_username	sherlock	Accounts across 300+ platforms
search_breach	HaveIBeenPwned API	Data breach exposure and leaked data
search_whois	python-whois	Domain registrant, registrar, dates
search_ip	ipinfo.io	Geolocation, ASN, hostname
search_domain	sublist3r	Subdomain enumeration
generate_dorks	built-in	12 targeted Google dork URLs
search_paste	psbdmp.ws	Pastebin dump mentions
search_phone	phoneinfoga	Carrier, country, line type
search_censys	Censys API	Open ports, services, certificate history
search_ip2location	IP2Location API	Geolocation, ISP, VPN/Proxy/Tor/Datacenter detection
search_abuseipdb	AbuseIPDB v2 API	IP abuse confidence score, reports, country, ISP

ℹ️ Note: The IP2Location integration is sponsored — a Security Plan API key is provided free of charge by IP2Location.

---

search_email

Enumerates online services linked to an email using holehe.

MCP parameter: email (string, required)

$ openosint email target@example.com -t 60

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

---

search_username

Searches 300+ platforms using sherlock.

MCP parameter: username (string, required)

$ openosint username johndoe99

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.

MCP parameter: email (string, required)

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

---

search_whois

Retrieves WHOIS registration data via python-whois.

MCP parameter: domain (string, required)

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

---

search_ip

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

MCP parameter: ip (string, required)

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

---

search_domain

Enumerates subdomains via sublist3r.

MCP parameter: domain (string, required)

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

---

generate_dorks

Generates 12 targeted Google dork URLs. No network calls required.

MCP parameter: target (string, required)

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

---

search_paste

Searches Pastebin dumps via psbdmp.ws.

MCP parameter: query (string, required)

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

---

search_phone

Phone intelligence via phoneinfoga. Use E.164 format.

MCP parameter: phone (string, required)

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

---

search_ip2location

Queries the IP2Location.io API for enhanced IP intelligence. Returns geolocation (country, region, city, coordinates, ZIP), ISP, domain, and ASN. On the Security Plan, also detects whether the address is a VPN, proxy, Tor exit node, or datacenter host. Sponsored integration.

MCP parameter: ip (string, required) — IPv4 or IPv6 address

Requires: IP2LOCATION_API_KEY environment variable — get one here

$ openosint ip2location 8.8.8.8
$ openosint ip2location 2001:4860:4860::8888
$ openosint ip2location 8.8.8.8 -t 30

[IP2Location] IP: 8.8.8.8
[IP2Location] Country: United States (US)
[IP2Location] Region: California
[IP2Location] City: Mountain View
[IP2Location] Latitude: 37.38605
[IP2Location] Longitude: -122.08385
[IP2Location] ZIP: 94035
[IP2Location] ISP: Google LLC
[IP2Location] Domain: google.com
[IP2Location] ASN: AS15169 Google LLC
[IP2Location] Proxy: No
[IP2Location] VPN: No
[IP2Location] TOR: No
[IP2Location] Datacenter: Yes
[IP2Location] Threat: clean

If a VPN, proxy, or Tor exit node is detected, the output appends: ⚠️ 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. Shows a prominent warning when score exceeds 50%.

MCP parameter: ip (string, required) — IPv4 or IPv6 address

Requires: ABUSEIPDB_API_KEY environment variable — get one here

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

email ADDRESS [-t SECONDS] — Enumerate services via holehe. Default timeout: 120s.

username HANDLE [-t SECONDS] — Enumerate platforms via sherlock. Default timeout: 180s.

Flag	Description
-v, --verbose	Enable debug logging to stderr.
-t, --timeout N	Override subprocess timeout (seconds).
--api-key KEY	Anthropic API key (overrides env var).

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"]
    }
  }
}

Interactive REPL:

$ openosint
openosint ❯ investigate target@example.com
openosint ❯ find all accounts for johndoe99
openosint ❯ what subdomains does example.com have?
openosint ❯ check if +14155552671 is mobile

Direct CLI:

$ openosint email target@example.com -t 60
$ openosint username johndoe99
$ openosint -v email target@example.com

Agentic via Claude Code:

$ claude
> Investigate target@example.com. Trace any username found
  across other platforms and compile a full report.

Path	Description
openosint/agent.py	AI agent loop (Anthropic tool use).
openosint/repl.py	Interactive REPL session.
openosint/mcp_server.py	MCP server entry point (stdio).
openosint/cli.py	CLI entry point.
openosint/tools/search_email.py	Email enumeration.
openosint/tools/search_username.py	Username enumeration.
openosint/tools/search_breach.py	Data breach check.
openosint/tools/search_whois.py	WHOIS lookup.
openosint/tools/search_ip.py	IP intelligence.
openosint/tools/search_domain.py	Subdomain enumeration.
openosint/tools/generate_dorks.py	Google dork generator.
openosint/tools/search_paste.py	Pastebin search.
openosint/tools/search_phone.py	Phone intelligence.
openosint/tools/search_ip2location.py	IP2Location enhanced IP intelligence.
openosint/tools/search_abuseipdb.py	IP abuse reputation module.
openosint/tools/exceptions.py	Shared exception hierarchy.
pyproject.toml	Build configuration (PEP 621).
DISCLAIMER.md	Legal notice and ethical use policy.

Code	Meaning
0	Successful execution.
1	General error (invalid arguments, tool failure).
130	Terminated by SIGINT (Ctrl-C).

openosint is for authorised security research, penetration testing, and investigative journalism only. Users are solely responsible for compliance with applicable law including GDPR, CCPA, and the Computer Fraud and Abuse Act.

Permitted	Prohibited
Authorised penetration testing	Stalking or harassment
Investigating your own accounts	Doxxing or targeted exposure
Journalistic investigation	Unauthorised surveillance
Law enforcement with legal basis	Identity theft or fraud

See DISCLAIMER.md for the full legal notice.

Released under the MIT License — free for any use: personal, commercial, SaaS, closed-source, academic. No purchase required. See LICENSE in the source distribution.

For organizations that need a vendor contract, written warranty, indemnification clause, or SLA on top of the MIT license, an optional commercial service agreement is available. Purchasing a plan does not restrict or replace your MIT rights — it is a separate service layer.

Tier	Price	What you get
Starter	€300 / year	Commercial use agreement, license assurance letter, email support
Business	€600 / year	Everything in Starter + priority support (2-day SLA), named contact, indemnification
Enterprise	€1,000+ / year	Everything in Business + SLA docs, compliance docs, vendor onboarding, PO/net-30

→ Full commercial plan details  ·  commercial@openosint.tech

Source code, issues, and contributions: github.com/OpenOSINT/OpenOSINT

$ git clone https://github.com/OpenOSINT/OpenOSINT.git
$ cd OpenOSINT
$ pip install -e .

Pull requests welcome. See DISCLAIMER.md before contributing.

OpenOSINT is proudly sponsored by IP2Location (IP Geolocation & IP Intelligence category).

Featured Integration sponsorships are available for four open categories: residential/datacenter proxy detection, breach/compromised-credential data, threat & domain intelligence, and email/identity lookup. One vendor per category — exclusive placement in the README, docs, CLI banner, and Web UI.

→ Full media kit and pricing — Open Collective — openosint@yahoo.com

OpenOSINT is free and MIT-licensed. The following is an optional paid setup service offered by the maintainer.

OSINT-MCP Setup Sprint — done-for-you installation and configuration of an autonomous OSINT-MCP pipeline on your environment. Fully async, no calls required.

Includes:

• Pre-configured OpenOSINT setup tailored to your stack (Claude Code, Claude Desktop, or any MCP client)
• API keys wired in — Shodan, VirusTotal, IP2Location, HaveIBeenPwned, and others as needed
• One investigation workflow built around your use case
• Written step-by-step setup guide + screen-recorded walkthrough
• 1-page runbook
• Async email support for 7 days

Delivery: 3–5 days, fully async.

For: SOC analysts · threat-intel teams · fraud/AML · pentesters · OSINT investigators

Founding pricing available for early teams — inquire.

→ Start · openosint@yahoo.com · LinkedIn

For authorised use only. See DISCLAIMER.md.

Free AI OSINT Prompt Starter Set — 5 structured prompts that make ChatGPT and Claude collect real data instead of hallucinating. Free PDF, instant download. Full 30+ pack ($29) ↗