Mrholmes

A professional, community-friendly OSINT operator kit that turns a broad collection of OSINT, cyber-reference, and pentest-adjacent repositories into one safe command surface and one MCP tool.

This repo is built for the person who finds it after hours of searching GitHub and wants the fastest sane path from clone to understanding to controlled execution.

• One entrypoint: mrholmes_suite.py
• One MCP tool: mrholmes
• 88 catalogued repositories
• 89 safe command surfaces
• Live/passive validation ledger included
• Risky repos are catalogued and searchable by default, not blindly executed

Operating stance

Professional OSINT work is disciplined: verify sources, preserve context, document uncertainty, and avoid unnecessary harm. This suite is designed for authorized research, blue-team enrichment, threat intelligence, public-source investigation, and controlled lab/pentest workflows.

It does not pretend every upstream repo is safe to run. High-risk repositories are exposed through static inventory/search/status wrappers unless a non-invasive execution path was deliberately verified.

Fast start

git clone https://github.com/Reaper-Legion/mrholmes-osint-suite.git
cd mrholmes-osint-suite
python -m py_compile mrholmes_suite.py mrholmes_mcp_server.py
python mrholmes_suite.py status
python mrholmes_suite.py mrholmes dorks example --dork-type 1 --timeout 120
python mrholmes_suite.py darkus-search example --limit 5 --timeout 30
python mrholmes_mcp_server.py

If you already maintain the upstream repos somewhere else, point the suite at that workspace:

export MRHOLMES_OSINT_ROOT=/path/to/osint-workspace
python mrholmes_suite.py status

What to run first

python mrholmes_suite.py status
python mrholmes_suite.py mrholmes username-profile example --timeout 300
python mrholmes_suite.py mrholmes domain example.com --timeout 180
python mrholmes_suite.py himitsu hash-type 5d41402abc4b2a76b9719d911017c592
python mrholmes_suite.py joas-blueguardian status
python mrholmes_suite.py joas-payloadsallthethings search osint --limit 10

MCP install

Use the single-tool MCP server when connecting from Hermes, Claude Desktop, Cursor, or another MCP client:

{
  "mcpServers": {
    "mrholmes": {
      "command": "python",
      "args": ["/absolute/path/to/mrholmes-osint-suite/mrholmes_mcp_server.py"]
    }
  }
}

The MCP server exposes exactly one tool:

• mrholmes

Tool actions:

• status
• catalog
• run
• tracker
• manifest
• live_test
• cleanup
• full_report

Example MCP payload:

{
  "action": "run",
  "argv": ["darkus-search", "example", "--limit", "5", "--timeout", "30"],
  "timeout": 60
}

Repo map

• mrholmes_suite.py — unified CLI/router.
• mrholmes_mcp_server.py — one-tool MCP stdio server.
• mrholmes_agent.py — non-interactive wrapper for upstream Mr.Holmes.
• joas-integration/ — static/safe wrappers for JoasASantos repos.
• cscorza-integration/ — wrappers for CScorza repos.
• MRHOLMES-SUITE-MANIFEST.json — catalogue, roles, automation posture.
• MRHOLMES-LIVE-TEST-LEDGER.json — passive/live validation record.
• docs/ — operator guide, MCP guide, ethics, command catalogue, testing notes.

Install philosophy

Minimal by design. Python stdlib runs the catalogue, static wrappers, MCP server, and many safe commands. Some upstream tools have their own dependencies; install those only when you are intentionally operating that tool in a controlled environment.

Professional use

• Work from explicit authorization.
• Prefer passive collection before active probing.
• Treat generated dorks as leads, not truth.
• Corroborate important findings from primary sources.
• Do not run payload, phishing, credential theft, C2, exploit, driver, or evasion code from this suite by default.
• Keep notes: target, scope, timestamp, source, confidence, and chain of custody.

Quick mental model

A good OSINT suite should make the safe thing the easy thing:

1. Discover what a repo is.
2. Read its role and risk posture.
3. Run only the wrapper surface that has been classified as safe.
4. Save evidence and uncertainty.
5. Escalate to active testing only in a scoped lab or authorized engagement.

See docs/GETTING_STARTED.md for the operator walkthrough.