osint-toolbox-mcp

An MCP server that lets AI agents run classic OSINT tools on your own machine: Sherlock, Maigret, Holehe, GHunt, theHarvester, SpiderFoot, Blackbird, PhoneInfoga and ExifTool. 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.

Tools

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: the server uses the tools installed on your machine.

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, install the tools you want and check what the server finds:

uvx osint-toolbox-mcp --check

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 (eight tools)	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. Otherwise install any subset. Put each Python tool in its own environment with uv tool install (or pipx install): their dependencies conflict with each other.

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.

Finally, check: uvx osint-toolbox-mcp --check lists every tool as ok, missing (with how to install it) or broken (found but fails to start).

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

  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?"
• "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 osint-toolbox-mcp --check (or docker run --rm ghcr.io/renkagod/osint-toolbox-mcp --check). 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.

License and credits

MIT, see LICENSE.

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