osint-toolbox-mcp

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.

Features

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.

Quick start

Pick one:

• Docker: every tool but Blackbird in one image, nothing else to install.
• uvx: one command installs the tools on your machine, without admin rights.

Docker

The image is large, so pull it once before adding the server; otherwise the first start can take longer than your client waits:

docker pull ghcr.io/renkagod/osint-toolbox-mcp

Add the server to your client:

{
  "mcpServers": {
    "osint-toolbox": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/renkagod/osint-toolbox-mcp"]
    }
  }
}

Files for ExifTool, the GHunt login, API keys and proxies are covered in Docker details.

uvx

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:

uvx osint-toolbox-mcp --install

Add the server to your client:

{
  "mcpServers": {
    "osint-toolbox": {
      "command": "uvx",
      "args": ["osint-toolbox-mcp"]
    }
  }
}

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.

Connect your client

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:

claude mcp add osint-toolbox -- uvx osint-toolbox-mcp
claude mcp add osint-toolbox -- docker run -i --rm ghcr.io/renkagod/osint-toolbox-mcp

Clients that read the mcpServers JSON above (paste it into the file):

Clients with their own format (shown with uvx; for Docker, use docker with the arguments run -i --rm ghcr.io/renkagod/osint-toolbox-mcp):

code --add-mcp '{"name":"osint-toolbox","command":"uvx","args":["osint-toolbox-mcp"]}'

{
  "servers": {
    "osint-toolbox": {
      "type": "stdio",
      "command": "uvx",
      "args": ["osint-toolbox-mcp"]
    }
  }
}

codex mcp add osint-toolbox -- uvx osint-toolbox-mcp

[mcp_servers.osint-toolbox]
command = "uvx"
args = ["osint-toolbox-mcp"]
tool_timeout_sec = 1800

{
  "context_servers": {
    "osint-toolbox": {
      "command": "uvx",
      "args": ["osint-toolbox-mcp"],
      "env": {}
    }
  }
}

extensions:
  osint-toolbox:
    name: osint-toolbox
    type: stdio
    cmd: uvx
    args: [osint-toolbox-mcp]
    enabled: true
    timeout: 1800

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "osint-toolbox": {
      "type": "local",
      "command": ["uvx", "osint-toolbox-mcp"],
      "enabled": true
    }
  }
}

name: OSINT Toolbox
version: 1.0.0
schema: v1
mcpServers:
  - name: osint-toolbox
    type: stdio
    command: uvx
    args:
      - osint-toolbox-mcp

Install the tools

Skip this if you use Docker, unless you want Blackbird.

uvx osint-toolbox-mcp --install

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:

• puts each Python tool (Sherlock, Holehe, Maigret, GHunt, theHarvester, dnstwist, dnsrecon) in its own environment with 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;
• downloads SpiderFoot and Blackbird from GitHub, each with its own virtual environment;
• downloads PhoneInfoga, subfinder and ExifTool and checks them against the checksums their authors publish. On macOS and Linux, ExifTool needs Perl, which those systems usually have.

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.

Installing by hand

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:

git clone https://github.com/smicallef/spiderfoot
cd spiderfoot
uv venv --python 3.12
uv pip install -r requirements.txt

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.

Configuration

All settings are environment variables, set in the env block of your client's config:

{
  "mcpServers": {
    "osint-toolbox": {
      "command": "uvx",
      "args": ["osint-toolbox-mcp"],
      "env": {
        "OSINT_SPIDERFOOT_DIR": "/home/me/spiderfoot",
        "OSINT_EXIFTOOL": "/opt/exiftool/exiftool"
      }
    }
  }
}

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.

Docker details

• 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:

  Terminal

  Copy

  docker run -it --rm --entrypoint ghunt -v osint-toolbox-ghunt:/home/osint/.malfrats ghcr.io/renkagod/osint-toolbox-mcp login
  

  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:

{
  "mcpServers": {
    "osint-toolbox": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/me/osint-files:/data:ro",
        "-v", "osint-toolbox-ghunt:/home/osint/.malfrats",
        "ghcr.io/renkagod/osint-toolbox-mcp"
      ]
    }
  }
}

Example requests

• "Which sites have an account registered to jane.doe@example.com?"
• "Search for the username jdoe_1987 with Sherlock and Maigret and compare what they find."
• "What subdomains and email addresses are public for example.com?"
• "Which lookalike domains of example.com are registered, and do any of them have mail servers?"
• "Who owns example.com and when does it expire? Show me how its homepage looked in 2015."
• "Read the metadata of /home/me/photo.jpg and tell me where and with what it was taken."
• "Run a passive SpiderFoot scan of example.com and summarize the findings."

Troubleshooting

• A tool is missing. Run 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.
• Long scans time out. Many clients stop waiting for a tool after a minute or so. Raise the limit where your client allows it: 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 fails. It needs a valid login: run ghunt login. When the saved session has been revoked, ghunt login itself fails; run ghunt login --clean to delete it, then ghunt login.
• Empty results, errors or captchas. Sites rate-limit and change their pages; retry later, lower the load, or go through a proxy. If a tool fails the same way outside the server, report it to that tool's project.
• Windows and .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.

Responsible use

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.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md. Changes are listed in the changelog.

Credits

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).

License

MIT — Copyright (c) 2026 renkagod.