DEV Community

Cover image for I built an MCP-native OSINT framework that lets AI agents investigate from your terminal
Tommaso Bertocchi
Tommaso Bertocchi

Posted on

I built an MCP-native OSINT framework that lets AI agents investigate from your terminal

#python #security #osint #mcp

You give Claude a single prompt — "investigate this email address" — and it autonomously chains five tools: email enumeration, username search across 300+ platforms, breach lookup, WHOIS, and IP geolocation. No manual invocations, no copy-pasting output between scripts, no babysitting. That's what OpenOSINT enables, and it works because the entire tool surface is exposed through the Model Context Protocol.

What is OpenOSINT?

OpenOSINT is a Python framework that acts as an MCP server, exposing 9 OSINT tools to any MCP-compatible AI client — Claude Code, Claude Desktop, or anything else that speaks the protocol. It is not a scraper, not a dashboard, not a GUI. It is a structured tool surface that lets LLMs call real intelligence-gathering utilities the same way they call any other function.

The framework wraps proven OSINT tools — holehe, sherlock, sublist3r, phoneinfoga, HaveIBeenPwned — in async, stateless Python functions that the MCP layer can discover and invoke.

OpenOSINT demo

Version 2.1.0 is live on PyPI, the repo is MIT-licensed, and it runs on Python 3.10+. If you know what OSINT is but have never had an AI agent drive an investigation autonomously, this is the fastest path to that experience.

Why MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. Instead of writing a custom function-calling wrapper for every LLM provider, you implement an MCP server once — define your tools, their input schemas, their descriptions — and any MCP-compatible client can discover and use them automatically.

For OSINT tooling, this matters. Before MCP, you had two options: hard-code investigation logic into a prompt (fragile, unmaintainable) or build a custom agent that calls tools via a provider-specific function-calling API (works, but locked to one provider and one integration pattern). With MCP, you expose OSINT capabilities as a server once, and every compatible client — Claude Code, Claude Desktop, or any future client — can drive investigations autonomously.

There's prior art here. A freeCodeCamp article explored building an autonomous OSINT agent using the Claude Tool Use API directly. OpenOSINT takes that concept and makes it protocol-native: the tools are not hard-wired to Claude's API, they're available to any MCP client. The result is that the same 9 tools work regardless of which AI client you're using, and you don't rewrite the integration every time the ecosystem changes.

The practical payoff: once your MCP server is registered, you stop thinking about which tool to call. You describe the investigation goal, and the agent decides which tools to chain, in what order, based on what it finds at each step.

The 9 Tools

Tool What it does External dependency
search_email Email account enumeration holehe
search_username Username search across 300+ platforms sherlock
search_breach Data breach check HaveIBeenPwned v3 API
search_whois WHOIS domain registration lookup python-whois
search_ip IP geolocation + ASN ipinfo.io
search_domain Subdomain enumeration sublist3r
generate_dorks Generates 12 targeted Google dork URLs none (no network calls)
search_paste Pastebin dump search psbdmp.ws
search_phone Phone carrier + country + line type phoneinfoga binary

Three tools worth showing in detail:

search_email runs an email address through holehe to check which online accounts are registered to it:

openosint search-email target@example.com
Enter fullscreen mode Exit fullscreen mode 
[+] twitter.com        → registered
[+] github.com         → registered
[-] instagram.com      → not found
[+] spotify.com        → registered
Enter fullscreen mode Exit fullscreen mode

search_username passes the username to sherlock and checks 300+ platforms:

openosint search-username johndoe42
Enter fullscreen mode Exit fullscreen mode 
[+] GitHub     → https://github.com/johndoe42
[+] Reddit     → https://reddit.com/user/johndoe42
[+] Twitter    → https://twitter.com/johndoe42
[-] TikTok     → not found
Enter fullscreen mode Exit fullscreen mode

search_ip queries ipinfo.io and returns geolocation, ASN, and organization data:

openosint search-ip 8.8.8.8
Enter fullscreen mode Exit fullscreen mode 
IP:           8.8.8.8
Hostname:     dns.google
City:         Mountain View
Region:       California
Country:      US
Organization: AS15169 Google LLC
ASN:          AS15169
Enter fullscreen mode Exit fullscreen mode

Architecture

OpenOSINT has three strict layers with one architectural rule: no layer imports from a layer above it.

Layer Path Responsibility
Core tools openosint/tools/ Async wrappers — stateless, no I/O, no UI
MCP server openosint/mcp_server.py Translates tools to MCP schemas, handles stdio transport
CLI openosint/cli.py Human-facing interface, formats output for the terminal

The core tools layer is where all the actual work happens. Each tool is a stateless async function that accepts typed inputs and returns structured data. It knows nothing about how it's being called. The MCP server layer reads those functions and exposes them as MCP tool definitions with JSON schemas. The CLI layer calls the same functions directly and handles terminal rendering.

This separation is what makes the MCP and CLI modes interchangeable. The same search_email async function runs whether Claude is calling it via MCP or you're typing a command in your terminal. No duplication, no drift between the two interfaces, no special-casing.

agent investigation

Installation

Clone the repo and install in editable mode:

git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .
Enter fullscreen mode Exit fullscreen mode

Install the external OSINT dependencies:

pip install holehe sherlock-project sublist3r
# phoneinfoga: download the binary from its GitHub releases page
# and ensure it's available on your PATH
Enter fullscreen mode Exit fullscreen mode

To register OpenOSINT as an MCP server in Claude Code:

claude mcp add openosint python /absolute/path/to/OpenOSINT/openosint/mcp_server.py
claude mcp list
Enter fullscreen mode Exit fullscreen mode

For Claude Desktop, add the server entry to your claude_desktop_config.json:

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

Restart Claude Desktop after saving. On next launch it will discover all 9 tools automatically — no further configuration needed.

Agentic OSINT in action

This is the use case that makes the MCP architecture worth it. Open Claude Code and type:

claude
Enter fullscreen mode Exit fullscreen mode

Then give it a single prompt:

Investigate target@example.com. If you find an associated username,
trace it across other platforms and compile a full report.
Enter fullscreen mode Exit fullscreen mode

Here's what happens internally, without any further input from you:

  1. Claude calls search_email with target@example.com
  2. The tool returns a list of platforms where the email is registered — including a recognizable username pattern
  3. Claude calls search_username with that username
  4. sherlock checks 300+ platforms and returns all profile URLs
  5. Claude calls search_breach to check if the email has appeared in known data breaches
  6. Claude synthesizes all results into a structured investigation report

No manual tool invocation. No copy-pasting output between commands. The agent decides the investigation path based on what it finds at each step. If search_email returns nothing actionable, it pivots — tries generate_dorks, calls search_whois, or runs search_paste. That's the difference between a collection of OSINT scripts and a tool surface that an agent can reason over.

AI agent working

Optional: Breach + Phone Intel

Two tools require additional setup to return full results.

search_breach uses the HaveIBeenPwned v3 API, which requires a paid API key for programmatic access. Set it as an environment variable before running:

export HIBP_API_KEY=your_key_here
Enter fullscreen mode Exit fullscreen mode

Once set, search_breach returns breach metadata for an email address:

target@example.com found in 3 breaches:
- LinkedIn (2012) — 164M accounts — passwords, emails
- Adobe (2013) — 153M accounts — passwords, emails, usernames
- Dropbox (2012) — 68M accounts — passwords, emails
Enter fullscreen mode Exit fullscreen mode

search_phone wraps the phoneinfoga binary, which must be on your PATH. You can optionally set IPINFO_TOKEN for enriched geolocation data on top of the carrier lookup:

export IPINFO_TOKEN=your_token_here
Enter fullscreen mode Exit fullscreen mode

Example output:

Phone:     +14155552671
Country:   United States
Carrier:   AT&T Mobility
Line type: mobile
Enter fullscreen mode Exit fullscreen mode

Both tools degrade gracefully if env vars are missing — search_breach returns a clear permissions error from the API, and search_phone falls back to basic carrier data. The rest of the framework continues working regardless.

What's next

The current tool set covers the core OSINT surface well, but the obvious next directions are more tools and tighter workflows. Near-term additions that would fit naturally: a search_certificate tool for certificate transparency log lookups (an underused source of subdomain and org data), a search_social tool for public social metadata aggregation, and piped workflow support so you can chain tools in a single CLI command without needing an AI client at all.

Longer term, a lightweight web UI that acts as an MCP client would make OpenOSINT accessible to teams who aren't running Claude Code. As more AI clients adopt the protocol, the value of the MCP architecture compounds — every new compatible client gets all 9 tools for free. If you want to add a tool, the contribution surface is clear: write a stateless async function in openosint/tools/, and the MCP server and CLI will pick it up automatically. Open an issue with your idea first, or submit a PR directly.

Star the repo if it's useful: https://github.com/OpenOSINT/OpenOSINT.

Wrapping up

OpenOSINT is what happens when you stop treating OSINT tools as standalone scripts and start treating them as a structured capability surface for AI agents. The Model Context Protocol makes that surface discoverable, composable, and client-agnostic. You get nine real tools, a clean three-layer architecture, and agentic investigation workflows that chain those tools autonomously based on what they find.

Install it, register the MCP server, and give Claude something to investigate. The half-hour setup is worth it.

OpenOSINT is for legal and authorized use only. Users are responsible for compliance with applicable laws in their jurisdiction.

Top comments (0)