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

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 N]             # direct email scan, no AI
openosint username HANDLE [-t N]           # direct username scan, no AI
openosint shodan QUERY [-t N]              # Shodan lookup, no AI
openosint multi TARGETS                    # multi-target parallel investigation
openosint --parallel email ADDRESS         # parallel: search_email + search_breach
openosint --parallel username HANDLE       # parallel: search_username + search_paste
openosint --json email ADDRESS             # JSON output
openosint --provider ollama                # use local Ollama instead of Anthropic
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 intelligently 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 10 tools to any MCP-compatible AI client (Claude Code, Claude Desktop).

The framework is built on Python asyncio. All external binaries run as managed subprocesses with hard timeout enforcement. The AI layer uses the Anthropic native tool use API — or a local Ollama model (no API key required). When using Anthropic, the model issues hard stops when it needs a tool, your code executes it, the real output goes back. Hallucination in tool results is structurally impossible.

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 .

Set your Anthropic API key (not required when using Ollama):

export ANTHROPIC_API_KEY=sk-ant-...

Optional: use a local Ollama model instead of Anthropic:

# Install Ollama from https://ollama.com, then:
ollama pull llama3.2
pip install ollama
openosint --provider ollama

External dependencies (must be present in PATH):

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

Optional environment variables:

Optional Python packages:

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 ────────────────────╮
  │ ## Summary                                     │
  │ Single target identified — high confidence.    │
  │                                                │
  │ ## Online Presence                             │
  │ Spotify · WordPress · Gravatar · Office365     │
  │                                                │
  │ ## Data Breaches                               │
  │ LinkedIn (2016) · Adobe (2013)                 │
  │                                                │
  │ ## Conclusion                                  │
  │ Moderate footprint. Credential rotation        │
  │ advised given breach exposure.                 │
  ╰────────────────────────────────────────────────╯

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

REPL commands:

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

Enumerates online services linked to an email address using holehe.

MCP parameter: email (string, required)

CLI:

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

Output:

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

Searches for a username across 300+ platforms using sherlock.

MCP parameter: username (string, required)

CLI:

$ openosint username johndoe99
$ openosint username johndoe99 -t 120

Output:

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

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

MCP parameter: email (string, required)

Output:

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

Retrieves WHOIS data for a domain using python-whois.

MCP parameter: domain (string, required)

Output:

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

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

MCP parameter: ip (string, required)

Output:

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

Enumerates subdomains using sublist3r.

MCP parameter: domain (string, required)

Output:

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

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

MCP parameter: target (string, required)

Output:

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

Searches Pastebin dumps via psbdmp.ws.

MCP parameter: query (string, required)

Output:

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

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

MCP parameter: phone (string, required)

Output:

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

Queries the Shodan API. If the query is an IPv4 address, performs a host lookup (open ports, org, vulnerabilities). Otherwise performs a keyword/banner search.

MCP parameter: query (string, required) — IP address or any Shodan search query

CLI:

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

Output:

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

Requires SHODAN_API_KEY environment variable.

email ADDRESS [-t SECONDS]

Enumerate services for ADDRESS via holehe. Default timeout: 120s.

username HANDLE [-t SECONDS]

Enumerate platforms for HANDLE via sherlock. Default timeout: 180s.

shodan QUERY [-t SECONDS]

Shodan host lookup (IP) or keyword search. Default timeout: 30s. Requires SHODAN_API_KEY.

multi TARGETS

Investigate multiple targets in parallel. TARGETS is either a comma-separated list or a path to a file with one target per line. Maximum 10 targets. Each target gets its own report; a summary report is also generated.

Flags:

# 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 in your shell before running docker compose.

Reports are persisted to ./reports/ via a volume mount.

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

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 [email protected]
openosint ❯ find all accounts for johndoe99
openosint ❯ what subdomains does example.com have?
openosint ❯ check if +14155552671 is a mobile number

Direct CLI:

$ openosint email [email protected] -t 60
$ openosint username johndoe99
$ openosint -v email [email protected]

Agentic via Claude Code:

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

Developed by Tommaso Bertocchi.

MIT License. See LICENSE.

OpenOSINT 2.5.0 — May 13, 2026