OSINT MCP

osint-mcp — Free OSINT Tools as MCP Tools for AI Agents

One command. 26 free OSINT tools. Any AI agent.

uvx osint-mcp   # installs everything and starts the MCP server

---

What is osint-mcp?

osint-mcp is a Python package that wraps 26 free OSINT (Open Source Intelligence) tools as MCP (Model Context Protocol) tools, giving AI agents like Claude, GPT-4, and any MCP-compatible agent the ability to perform real OSINT investigations directly from a conversation.

The problem it solves: Running OSINT tools traditionally requires installing a dozen separate binaries, writing glue scripts, and manually parsing outputs. osint-mcp automates the entire setup — it detects your OS, installs all tools via Homebrew / apt / Go / pip, and exposes them to your AI agent through a single MCP server.

Who it is for:

• Security researchers and penetration testers who want AI-assisted reconnaissance
• Developers building AI agents with security investigation capabilities
• Bug bounty hunters automating initial footprinting
• Threat intelligence analysts enriching IOCs (Indicators of Compromise)
• Students learning OSINT with AI guidance

---

Key Features

• 26 free OSINT tools spanning network, domain, social media, email, web, phone, and secrets scanning
• Single-command setup — uvx osint-mcp auto-installs all underlying tools on first run
• MCP-native — works out of the box with Claude Desktop, any MCP client, or the Anthropic SDK
• Zero-config for most tools — 15 tools work with no API key at all
• Graceful degradation — tools with optional free API keys (Shodan, VirusTotal) work in reduced mode without them and tell you exactly how to enable full access
• macOS + Linux support (Homebrew, apt, yum, Go, pip — all detected automatically)
• Safe by default — passive recon only unless you explicitly call a port-scan or secrets-scan tool

---

One-Command Setup (Recommended)

uvx is the Python equivalent of npx — it installs the package in an isolated environment and runs it immediately. No pip install, no virtual environment setup needed.

uvx osint-mcp

On first run, this automatically:

1. Installs osint-mcp in an isolated Python environment
2. Detects your OS (macOS or Linux)
3. Installs all 26 OSINT tool binaries via Homebrew / apt / Go / uv pip
4. Starts the MCP server on stdio (ready for Claude Desktop or any MCP client)

On subsequent runs, it boots in under a second — tools are already installed.

---

Connect to Claude Desktop

Add one entry to your Claude Desktop config and you are done.

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json Linux — ~/.config/Claude/claude_desktop_config.json

{

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

Restart Claude Desktop. You will see 26 new OSINT tools available in the tool list.

---

Alternative: Traditional pip Install

If you prefer managing your own environment:

pip install osint-mcp

Install all OSINT tool binaries

osint-mcp install

Check what is available

osint-mcp status

Start the MCP server

osint-mcp serve

---

How It Works

Claude Desktop / AI Agent

│ │ MCP (stdio) ▼ osint-mcp server │ ├── osint_whois → python-whois library ├── osint_port_scan → nmap binary (subprocess) ├── osint_subdomain_enum → subfinder binary ├── osint_cert_transparency → crt.sh public API (HTTP) ├── osint_shodan_host → Shodan REST API (optional key) ├── osint_virustotal → VirusTotal REST API (optional key) └── ... 20 more tools

Each tool is a BaseTool subclass. The registry auto-discovers all subclasses at startup and registers them with FastMCP. If a tool's binary is not installed, it returns a clear "not installed — run osint-mcp install" message instead of crashing.

---

Complete Tool Reference (26 Tools)

Network Intelligence

Domain & DNS Intelligence

Social Media & Username OSINT

Email Intelligence

Web & Threat Intelligence

Phone Number OSINT

Secrets & Code Scanning

Meta / Utility

---

Optional Free API Keys

These tools work without a key but unlock significantly more data with one. All are free to register.

# Set a key via CLI

osint-mcp config set shodan_key=YOUR_KEY

Or let your AI agent set it during a conversation (via osint_config_set tool)

---

Example AI Agent Conversations

Once connected to Claude Desktop, you can ask questions like:

*"Investigate the domain example.com — find subdomains, check for data breaches on contact emails, and look it up on Shodan."*

*"Scan the GitHub repo github.com/org/repo for exposed secrets and API keys."*

*"Find all social media accounts associated with the username johndoe123."*

*"Check if the IP 1.2.3.4 is listed on Shodan and what ports are open."*

*"Look up the phone number +14155552671 and find what carrier and country it's registered to."*

The agent automatically chains multiple tools, interprets the results, and presents a coherent investigation summary — no manual tool orchestration needed.

---

CLI Reference

osint-mcp                          Start the MCP server (default, same as serve)

osint-mcp serve Start the MCP server explicitly osint-mcp serve --no-auto-install Skip first-run tool installation osint-mcp install Install all missing OSINT tools osint-mcp install --category X Install only tools in category (network/domain/social…) osint-mcp install --dry-run Preview what would be installed osint-mcp status Show a table of all tools and their availability osint-mcp config set KEY=VALUE Store an API key osint-mcp config get KEY Read a stored key (masked) osint-mcp config list List all stored keys osint-mcp config delete KEY Remove a key osint-mcp --version Print version osint-mcp --help Show help

---

Supported Platforms

Prerequisites auto-handled:

• Homebrew — must be pre-installed on macOS (https://brew.sh)
• Go 1.21+ — required for subfinder, amass, phoneinfoga, gitleaks (installer skips gracefully if absent)
• Python 3.10+ — required (bundled when using uvx)

---

Frequently Asked Questions

Q: What is MCP (Model Context Protocol)? A: MCP is an open standard by Anthropic that lets AI models call external tools in a structured, secure way. It is to AI agents what HTTP is to web browsers — a universal protocol for tool use. Learn more at modelcontextprotocol.io.

Q: Does osint-mcp work with AI agents other than Claude? A: Yes. Any MCP-compatible client works — including OpenAI's agent framework (via MCP adapters), LangChain, LlamaIndex, and custom agents built with the Anthropic SDK. The server communicates over stdio using the standard MCP JSON-RPC protocol.

Q: Does it cost anything? A: The package itself is free and open source. All 26 tools are free. Some tools (Shodan, VirusTotal) require a free API key registration for full functionality but offer a usable free tier.

**Q: Is it