OPENOSINT(1) — General Commands Manual

Name: OpenOSINT
Author: OpenOSINT

Legal notice: For authorised security research and investigation only.
Users are solely responsible for compliance with applicable law.
See DISCLAIMER.md.

NAME

openosint — Model Context Protocol server and CLI for Open Source Intelligence.

---

SYNOPSIS

openosint [-v] command [args ...]
openosint email ADDRESS [-t SECONDS]
openosint username HANDLE [-t SECONDS]

DESCRIPTION

openosint is a modular OSINT framework that exposes intelligence-gathering
tools to large language models via the Anthropic Model Context Protocol (MCP).
It also operates as a conventional command-line interface for direct human
execution.

The framework is built on a non-blocking asynchronous runtime (Python asyncio).
All external binaries are invoked as managed subprocesses with hard timeout
enforcement. No LLM is embedded; openosint provides the tool surface that
an MCP-compatible client drives autonomously.

ARCHITECTURE

The project follows a strict three-tier separation:

Layer	Path	Responsibility
Core tools	`openosint/tools/`	Async wrappers around external OSINT binaries. No I/O, no UI.
MCP server	`openosint/mcp_server.py`	Translates core functions into MCP tool schemas. Routes LLM calls.
CLI	`openosint/cli.py`	Human-facing interface. Calls core tools directly.

No layer imports from a layer above it. The core tools are stateless and have
no knowledge of MCP or argparse.

INSTALLATION

Requires Python 3.10 or later.

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

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`

If a binary is absent, the corresponding tool returns a descriptive error string.
The server and CLI remain operational for tools with satisfied dependencies.

COMMANDS

email ADDRESS [-t SECONDS]

Enumerate online services registered against ADDRESS using holehe.
Default timeout: 120 seconds.

username HANDLE [-t SECONDS]

Enumerate platforms where HANDLE is registered using sherlock.
Default timeout: 180 seconds.

Global flags:

-v, --verbose     Enable debug-level logging to stderr.
-t, --timeout N   Override default subprocess timeout (seconds).

CONFIGURATION

Claude Code

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

Verify:

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

EXAMPLES

Enumerate services registered against an email address:

$ openosint email [email protected] -t 60

Search for a username across all supported platforms:

$ openosint username johndoe99

Enable verbose output:

$ openosint -v email [email protected]

Agentic execution via Claude Code after MCP registration:

$ claude
> Investigate [email protected]. If you find an associated username,
  trace it across other platforms and compile a report.

FILES

Path	Description
`openosint/mcp_server.py`	MCP server entry point (stdio transport).
`openosint/cli.py`	CLI entry point.
`openosint/tools/search_email.py`	Email enumeration module.
`openosint/tools/search_username.py`	Username enumeration module.
`openosint/tools/exceptions.py`	Shared exception hierarchy.
`pyproject.toml`	Project metadata and build configuration (PEP 621).
`DISCLAIMER.md`	Legal notice and ethical use policy.

EXIT STATUS

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

AUTHORS

Developed by Tommaso Bertocchi.

LICENSE

MIT License. See LICENSE.

OpenOSINT 2.0.0 — May 10, 2026