The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the OSINT Toolbox listing page.
An MCP server that lets AI agents run classic OSINT tools on your own machine: Sherlock, Maigret, Blackbird, Holehe, GHunt, theHarvester, SpiderFoot, subfinder, dnstwist, dnsrecon, PhoneInfoga and ExifTool, plus built-in WHOIS, DNS, certificate transparency and Wayback Machine lookups. No API keys and no cloud service in between: the tools run locally and query public sources directly.
Ask your assistant "which sites have an account for jane@example.com?" or "what can you find about example.com?", and it picks the tools, runs them and reads the results for you.
| Tool | Give it | You get | Needs |
|---|---|---|---|
sherlock_username_search | username | accounts on 400+ sites | Sherlock |
maigret_username_search | username | accounts on up to 3000+ sites, with the profile data found on them | Maigret |
blackbird_username_search | username | accounts on the 700+ sites of the WhatsMyName list | Blackbird checkout (not in the Docker image) |
holehe_email_search | email address | which of about 120 sites have an account for it | Holehe |
ghunt_google_search | Google account email or Gaia ID | name, profile picture, Maps reviews, calendar and other public data | GHunt, logged in |
theharvester_domain_search | domain or company name | email addresses, subdomains, hosts, IP addresses | theHarvester |
spiderfoot_scan | domain, IP, email, phone, username, person name... | findings grouped by type | SpiderFoot checkout |
phoneinfoga_scan | phone number | country, number formats, carrier (with an API key), search queries | PhoneInfoga |
exiftool_metadata | path to a local file | GPS coordinates, camera, author, software, timestamps | ExifTool |
subfinder_subdomain_search | domain | subdomains from passive sources, with the sources that reported them | subfinder |
dnstwist_lookalike_domains | domain | registered lookalike domains (typos, homoglyphs, other TLDs) with their A, MX and NS records | dnstwist |
dnsrecon_domain_scan | domain | DNS records, zone transfer attempts, DNSSEC zone walking | dnsrecon |
whois_lookup | domain, IP address, network or AS number | registrar, dates, name servers, holder and contacts where public (RDAP, or WHOIS) | built in |
dns_lookup | domain name or IP address | A, AAAA, CNAME, MX, NS, TXT, SOA, CAA records, or the reverse name | built in |
crtsh_certificate_search | domain | host names and email addresses from TLS certificates issued for it (crt.sh) | built in |
wayback_snapshots | URL or domain | archived snapshots in the Wayback Machine, newest first | built in |
osint_toolbox_status | nothing | which tools are installed, and how to install the missing ones | built in |
Only installed tools are offered to the agent. Runs take from seconds to half an hour (a full SpiderFoot scan); requests run in parallel and can be cancelled.
Pick one:
The image is large, so pull it once before adding the server; otherwise the first start can take longer than your client waits:
Add the server to your client:
Files for ExifTool, the GHunt login, API keys and proxies are covered in Docker details.
Install uv, then install the tools. This installs everything that is missing and checks that each tool starts; see Install the tools for what it does:
Add the server to your client:
To run the latest code from main instead of a release, use uvx --from git+https://github.com/renkagod/osint-toolbox-mcp osint-toolbox-mcp.
One-click install:
| Client | Docker (all but Blackbird) | uvx (your tools) |
|---|---|---|
| Cursor | ||
| VS Code | ||
| VS Code Insiders | ||
| LM Studio |
Claude Desktop: download osint-toolbox-mcp-<version>.mcpb from the latest release and open it. Claude Desktop installs it as an extension and asks for the optional SpiderFoot, Blackbird and ExifTool locations; the other tools are found on PATH. You can also paste the JSON above into Settings → Developer → Edit Config.
Claude Code:
Clients that read the mcpServers JSON above (paste it into the file):
| Client | Where the config lives |
|---|---|
| Cursor | ~/.cursor/mcp.json, or .cursor/mcp.json in a project |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Cline | MCP Servers → Configure → cline_mcp_settings.json |
| Roo Code | .roo/mcp.json in a project, or the global MCP settings |
| Gemini CLI | ~/.gemini/settings.json |
| Antigravity | agent panel "…" → MCP Servers → Manage MCP Servers → View raw config |
| LM Studio | Program tab → Install → Edit mcp.json |
| Kiro | ~/.kiro/settings/mcp.json, or .kiro/settings/mcp.json in a project |
Clients with their own format (shown with uvx; for Docker, use docker with the arguments run -i --rm ghcr.io/renkagod/osint-toolbox-mcp):
Or in .vscode/mcp.json:
Or in ~/.codex/config.toml, with a longer timeout for slow scans:
In settings.json:
In ~/.config/goose/config.yaml:
In opencode.json:
In .continue/mcpServers/osint-toolbox.yaml:
Skip this if you use Docker, unless you want Blackbird.
installs every tool that is missing, without admin rights, then checks that each one starts. uvx osint-toolbox-mcp --install sherlock maigret installs only the tools named. It needs uv and:
uv tool install, on Python 3.12: their dependencies conflict with each other, and some have no builds for newer Pythons. theHarvester and dnsrecon come from their latest GitHub releases;Checkouts and downloads go to %LOCALAPPDATA%\osint-toolbox-mcp on Windows, ~/Library/Application Support/osint-toolbox-mcp on macOS and ~/.local/share/osint-toolbox-mcp on Linux; set OSINT_TOOLBOX_HOME to use another folder. The server looks there by itself. GHunt still needs a one-time ghunt login afterwards.
uvx osint-toolbox-mcp --check shows, at any time, every tool as ok, missing (with how to install it) or broken (found but fails to start). The agent can ask the same through the osint_toolbox_status tool.
| Tool | Install | Tested with |
|---|---|---|
| Sherlock | uv tool install sherlock-project | 0.16 |
| Holehe | uv tool install holehe | 1.61 |
| Maigret | uv tool install maigret | 0.6 |
| GHunt | uv tool install ghunt, then ghunt login | 2.3.4 |
| theHarvester | uv tool install git+https://github.com/laramies/theHarvester@4.11.1, or its newest release tag | 4.11.1 |
| dnstwist | uv tool install dnstwist --with dnspython --with tld --with idna | 20250130 |
| dnsrecon | uv tool install git+https://github.com/darkoperator/dnsrecon@1.6.3, or its newest release tag | 1.6.3 |
| subfinder | a binary from its releases, on PATH | 2.16.0 |
| PhoneInfoga | a binary from its releases, on PATH | 2.11.0 |
| ExifTool | exiftool.org, brew install exiftool or apt install libimage-exiftool-perl | 13.59 |
| SpiderFoot | a checkout, see below | commit 0f815a2 |
| Blackbird | a checkout, see below | commit b455050 |
If a Python tool fails to build on your default Python, add --python 3.12 to its uv tool install.
SpiderFoot and Blackbird run from git checkouts. Give each its own .venv, which the server picks up automatically, and tell the server where the checkout is:
Then set OSINT_SPIDERFOOT_DIR to that folder in your client's config (env). Blackbird is the same with https://github.com/antoniaci/blackbird and OSINT_BLACKBIRD_DIR. SpiderFoot pins lxml<5, which has no builds for Python 3.13 and newer; to use a newer Python, apply patches/spiderfoot-requirements.patch first.
All settings are environment variables, set in the env block of your client's config:
| Variable | Meaning |
|---|---|
OSINT_SHERLOCK, OSINT_HOLEHE, OSINT_MAIGRET, OSINT_GHUNT, OSINT_THEHARVESTER, OSINT_SUBFINDER, OSINT_DNSTWIST, OSINT_DNSRECON, OSINT_PHONEINFOGA, OSINT_EXIFTOOL | Full path to the tool, when it isn't on PATH |
OSINT_SPIDERFOOT_DIR, OSINT_BLACKBIRD_DIR | Folder of the SpiderFoot or Blackbird checkout |
OSINT_SPIDERFOOT_PYTHON, OSINT_BLACKBIRD_PYTHON | Python to run the checkout with; by default its .venv, then python on PATH |
OSINT_TOOLBOX_HOME | Where --install puts checkouts and downloads, and where the server looks for them |
OSINT_MAX_OUTPUT_CHARS | Longest result returned to the model, 100000 by default; 0 for no limit |
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY | Used by the built-in lookups and --install (HTTP and SOCKS5 proxies), and passed on to the tools, which may or may not use them |
Besides PATH, the server looks in the --install folder and in the folders uv tool and pipx install into (~/.local/bin by default), which desktop apps often leave out of PATH.
Blackbird is not in the image: it has no license that allows redistributing it. Install it yourself to use it.
ExifTool: the container sees only mounted files. Add -v /path/to/files:/data:ro to the arguments and ask about /data/photo.jpg.
GHunt: log in once into a named volume, then mount it:
GHunt's listening mode (option 1) doesn't work in a container; pick option 2 (paste from the GHunt Companion extension) or 3 (an oauth_token, see GHunt's README).
API keys: theHarvester reads /home/osint/.theHarvester/api-keys.yaml (mount your file there), PhoneInfoga reads its keys from environment variables (-e NAME=value).
Proxy: -e HTTPS_PROXY=http://host.docker.internal:8080, for example.
Tags: latest and version tags such as 1.0.0 for releases, edge for the current main. Built for linux/amd64 and linux/arm64.
A full configuration:
uvx osint-toolbox-mcp --install, or --check to see why a tool isn't found (docker run --rm ghcr.io/renkagod/osint-toolbox-mcp --check for the image). After installing, restart your client so it lists the new tools. Desktop apps often start servers with a shorter PATH than your terminal; set the tool's OSINT_* variable to its full path.MCP_TOOL_TIMEOUT in milliseconds for Claude Code, tool_timeout_sec for Codex CLI, timeout in milliseconds on the server entry for Gemini CLI, timeout in seconds for Goose. Otherwise ask for faster runs: a passive SpiderFoot scan, Maigret without all_sites.ghunt login. When the saved session has been revoked, ghunt login itself fails; run ghunt login --clean to delete it, then ghunt login..bat or .cmd wrappers. Arguments to such wrappers pass through cmd.exe, so the server refuses inputs with characters like & or |; point the OSINT_* variable at the real executable instead.These tools collect information about real people and organizations. Use them only where you have a lawful basis and authorization: your own accounts, security assessments within scope, research that respects privacy law (GDPR, CCPA and local equivalents) and the sites' terms of service. Don't use them to stalk, harass, dox or otherwise harm anyone. You are responsible for what you run and for what you do with the results.
Issues and pull requests are welcome; see CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md. Changes are listed in the changelog.
The tools belong to their authors and keep their own licenses: Sherlock, Maigret, Holehe, GHunt, theHarvester, SpiderFoot, Blackbird, PhoneInfoga, ExifTool. The server starts them as separate programs; the Docker image contains them unmodified.
This project started from frishtik/osint-tools-mcp-server (MIT).