osint-tools-mcp-server

OSINT Tools MCP Server Skill

Skill by ara.so — MCP Skills collection.

This MCP server provides AI assistants with access to multiple industry-standard OSINT (Open Source Intelligence) tools for reconnaissance and information gathering. It exposes 7 powerful tools through the Model Context Protocol: Sherlock, Holehe, SpiderFoot, GHunt, Maigret, TheHarvester, and Blackbird.

What It Does

The OSINT Tools MCP Server allows AI assistants to:

• Search usernames across 399+ social media platforms (Sherlock)
• Verify email registrations on 120+ platforms (Holehe)
• Perform comprehensive OSINT on IPs, domains, emails, phones, etc. (SpiderFoot)
• Extract Google account intel from emails or Google IDs (GHunt)
• Advanced username search across 3000+ sites with confidence scoring (Maigret)
• Gather domain intelligence including emails, subdomains, hosts (TheHarvester)
• Fast username reconnaissance across 581 sites (Blackbird)

Installation

Basic Setup

1. Clone the repository:

git clone https://github.com/frishtik/osint-tools-mcp-server.git
cd osint-tools-mcp-server

2. Install core dependencies:

pip install -r requirements.txt

This automatically installs: Sherlock, Holehe, Maigret, and TheHarvester.

3. Configure Claude Desktop:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "osint-tools": {
      "command": "python",
      "args": ["/absolute/path/to/osint-tools-mcp-server/src/osint_tools_mcp_server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

4. Restart Claude Desktop to load the MCP server.

Optional Tools Installation

SpiderFoot

git clone https://github.com/smicallef/spiderfoot.git /opt/spiderfoot
cd /opt/spiderfoot
pip install -r requirements.txt

GHunt

git clone https://github.com/mxrch/GHunt.git /opt/ghunt
cd /opt/ghunt
pip install -r requirements.txt

Blackbird

git clone https://github.com/p1ngul1n0/blackbird.git /opt/blackbird
cd /opt/blackbird
pip install -r requirements.txt

MCP Server Architecture

The server exposes tools as MCP resources. Each tool runs as a subprocess with timeout handling:

# Core structure from osint_tools_mcp_server.py
import asyncio
from mcp.server import Server
from mcp.types import Tool, TextContent

app = Server("osint-tools-mcp-server")

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="sherlock",
            description="Search for username across 399+ social media platforms",
            inputSchema={
                "type": "object",
                "properties": {
                    "username": {"type": "string", "description": "Username to search for"}
                },
                "required": ["username"]
            }
        ),
        # ... other tools
    ]

Available Tools & Usage

1. Sherlock - Username Search

Tool Name: sherlock

Input:

• username (string, required): Username to search for

Example Request:

Search for username "johndoe123" across social media platforms

What It Does: Searches 399+ platforms including Twitter, Instagram, GitHub, Reddit, etc.

Typical Response:

[+] Facebook: https://www.facebook.com/johndoe123
[+] Instagram: https://www.instagram.com/johndoe123
[+] GitHub: https://www.github.com/johndoe123
[-] Twitter: Not Found

2. Holehe - Email Verification

Tool Name: holehe

Input:

• email (string, required): Email address to check

Example Request:

Check if john.doe@example.com is registered on any platforms

What It Does: Verifies email registration on 120+ platforms (Google, Twitter, Adobe, etc.)

Typical Response:

[+] Google: Registered
[+] Twitter: Registered
[+] Adobe: Registered
[-] Amazon: Not Found

3. SpiderFoot - Comprehensive OSINT

Tool Name: spiderfoot

Input:

• target (string, required): IP, domain, email, phone, username, person name, Bitcoin address, or network block

Example Request:

Run comprehensive OSINT scan on example.com

What It Does: Deep reconnaissance with automatic target type detection. Scans 200+ modules including DNS, WHOIS, threat intelligence, social media, etc.

⚠️ Warning: Takes 5-30 minutes to complete. Very thorough.

Typical Response:

Target: example.com
Type: Domain
Modules Run: 156

WHOIS Data:
  Registrar: Example Registrar Inc.
  Created: 2020-01-15
  
DNS Records:
  A: 192.0.2.1
  MX: mail.example.com
  
Subdomains Found:
  - www.example.com
  - mail.example.com
  - api.example.com

4. GHunt - Google Account Intelligence

Tool Name: ghunt

Input:

• email (string, required): Email or Google ID

Example Request:

Extract information from Google account john.doe@gmail.com

What It Does: Retrieves Google account details, profile information, YouTube channels, Google Maps reviews, etc.

Typical Response:

Name: John Doe
Profile Picture: [URL]
Google ID: 123456789012345678901
YouTube Channel: [URL]
Reviews: 15 Google Maps reviews found
Last Profile Update: 2024-03-15

5. Maigret - Advanced Username Search

Tool Name: maigret

Input:

• username (string, required): Username to search for

Example Request:

Search for username "hackerman2024" with detailed analysis

What It Does: Searches 3000+ sites with false positive detection and confidence scoring.

Typical Response:

Username: hackerman2024
Sites Checked: 3127
Found: 47 profiles

High Confidence (90%+):
  - GitHub: https://github.com/hackerman2024
  - Reddit: https://reddit.com/u/hackerman2024
  
Medium Confidence (60-90%):
  - HackerNews: https://news.ycombinator.com/user?id=hackerman2024
  
Additional Data Extracted:
  - Real Name: John Smith (from GitHub)
  - Location: San Francisco (from Reddit)

6. TheHarvester - Domain Intelligence

Tool Name: theharvester

Input:

• domain (string, required): Domain or company name

Example Request:

Gather emails and subdomains for example.com

What It Does: Collects emails, subdomains, hosts, employee names from search engines, PGP servers, SHODAN, etc.

Typical Response:

Domain: example.com

Emails Found:
  - contact@example.com
  - admin@example.com
  - support@example.com
  
Hosts/Subdomains:
  - www.example.com (192.0.2.1)
  - mail.example.com (192.0.2.2)
  - api.example.com (192.0.2.3)
  
Employee Names:
  - John Doe
  - Jane Smith

7. Blackbird - Fast Username OSINT

Tool Name: blackbird

Input:

• username (string, required): Username to search for

Example Request:

Quick search for username "anonymous123"

What It Does: Lightning-fast searches across 581 sites optimized for speed.

Typical Response:

Username: anonymous123
Sites: 581 checked in 12 seconds

Found (24):
  [+] Twitter: https://twitter.com/anonymous123
  [+] Instagram: https://instagram.com/anonymous123
  [+] TikTok: https://tiktok.com/@anonymous123
  ...

Common Usage Patterns

Pattern 1: Email Investigation

User: "Investigate email address suspicious@example.com"

AI Response:
1. Running Holehe to check platform registrations...
2. Extracting domain and running TheHarvester...
3. Checking for Google account with GHunt...

Pattern 2: Username Footprint Analysis

User: "Find all accounts for username 'targetuser'"

AI Response:
1. Running Sherlock for broad search (399 platforms)...
2. Running Maigret for detailed analysis (3000+ sites)...
3. Cross-referencing results for high-confidence matches...

Pattern 3: Domain Reconnaissance

User: "Perform reconnaissance on competitor.com"

AI Response:
1. Running TheHarvester to gather emails and subdomains...
2. Launching SpiderFoot for comprehensive scan (this will take 15-20 minutes)...
3. While waiting, analyzing found email addresses with Holehe...

Pattern 4: Parallel Tool Execution

User: "Search for 'johndoe' quickly across multiple tools"

AI Response:
Running parallel searches:
- Sherlock (username search)
- Blackbird (fast username search)
- Holehe (checking johndoe@gmail.com, johndoe@yahoo.com)

Code Examples

Implementing a New Tool

To add a new OSINT tool to the server:

# In src/osint_tools_mcp_server.py

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        # ... existing tools ...
        Tool(
            name="newtool",
            description="Description of what the new tool does",
            inputSchema={
                "type": "object",
                "properties": {
                    "target": {
                        "type": "string",
                        "description": "Target to investigate"
                    },
                    "options": {
                        "type": "string",
                        "description": "Optional parameters",
                        "default": ""
                    }
                },
                "required": ["target"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "newtool":
        target = arguments["target"]
        options = arguments.get("options", "")
        
        # Build command
        cmd = ["newtool", target]
        if options:
            cmd.extend(options.split())
        
        # Execute with timeout
        try:
            process = await asyncio.create_subprocess_exec(
                *cmd,
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE
            )
            
            stdout, stderr = await asyncio.wait_for(
                process.communicate(),
                timeout=300  # 5 minute timeout
            )
            
            result = stdout.decode('utf-8', errors='replace')
            
            return [TextContent(
                type="text",
                text=f"New Tool Results:\n{result}"
            )]
            
        except asyncio.TimeoutError:
            return [TextContent(
                type="text",
                text="Tool execution timed out after 5 minutes"
            )]
        except Exception as e:
            return [TextContent(
                type="text",
                text=f"Error running tool: {str(e)}"
            )]

Custom Tool Wrapper

Creating a Python wrapper for better control:

import subprocess
import json
from typing import Dict, List

class OSINTToolWrapper:
    """Wrapper for OSINT tools with standardized output"""
    
    def __init__(self, tool_name: str, tool_path: str):
        self.tool_name = tool_name
        self.tool_path = tool_path
    
    async def execute(self, target: str, timeout: int = 300) -> Dict:
        """Execute tool and return structured results"""
        cmd = [self.tool_path, target, "--json"]
        
        try:
            process = await asyncio.create_subprocess_exec(
                *cmd,
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE
            )
            
            stdout, stderr = await asyncio.wait_for(
                process.communicate(),
                timeout=timeout
            )
            
            # Parse JSON output if available
            try:
                results = json.loads(stdout.decode('utf-8'))
            except json.JSONDecodeError:
                results = {"raw_output": stdout.decode('utf-8')}
            
            return {
                "tool": self.tool_name,
                "target": target,
                "success": process.returncode == 0,
                "results": results,
                "error": stderr.decode('utf-8') if stderr else None
            }
            
        except asyncio.TimeoutError:
            return {
                "tool": self.tool_name,
                "target": target,
                "success": False,
                "error": f"Timeout after {timeout} seconds"
            }

# Usage
sherlock = OSINTToolWrapper("sherlock", "/usr/local/bin/sherlock")
results = await sherlock.execute("johndoe")

Configuration

Environment Variables

Set these in your MCP server configuration:

{
  "mcpServers": {
    "osint-tools": {
      "command": "python",
      "args": ["/path/to/osint_tools_mcp_server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "SPIDERFOOT_PATH": "/opt/spiderfoot",
        "GHUNT_PATH": "/opt/ghunt",
        "BLACKBIRD_PATH": "/opt/blackbird",
        "OSINT_TIMEOUT": "300",
        "OSINT_LOG_LEVEL": "INFO"
      }
    }
  }
}

Tool-Specific Configuration

SpiderFoot Configuration:

# Edit /opt/spiderfoot/sfwebui.py for custom settings
# Or use environment variables
export SPIDERFOOT_MODULES="all"  # Or comma-separated list
export SPIDERFOOT_TIMEOUT="1800"  # 30 minutes

TheHarvester Sources:

# Specify data sources
theharvester -d example.com -b google,bing,linkedin,pgp

Maigret Verbosity:

# Control output detail
maigret username --no-progressbar --folderoutput ./results

Troubleshooting

Tools Not Found

Problem: Command not found: sherlock

Solution:

# Check installation
pip list | grep sherlock

# Install if missing
pip install sherlock-project

# Verify PATH
which sherlock

# Add to PATH if needed
export PATH="$PATH:$HOME/.local/bin"

SpiderFoot Not Running

Problem: SpiderFoot scans fail or timeout

Solution:

# Verify installation
cd /opt/spiderfoot
python sf.py -h

# Check dependencies
pip install -r requirements.txt

# Test manually
python sf.py -s example.com -m all -o json

Timeout Issues

Problem: Tools timeout before completing

Solution: Increase timeout in the MCP server code:

# For long-running tools like SpiderFoot
stdout, stderr = await asyncio.wait_for(
    process.communicate(),
    timeout=1800  # 30 minutes instead of default 5
)

Or use environment variable:

export OSINT_TIMEOUT="1800"

Rate Limiting

Problem: Getting blocked by platforms

Solution:

# Add delays between requests
sherlock username --timeout 10

# Use Tor for anonymity (if legal in your jurisdiction)
maigret username --tor

# Spread requests over time
# Run in batches with pauses

JSON Parsing Errors

Problem: Tool output not parsing correctly

Solution:

# Add error handling
try:
    results = json.loads(output)
except json.JSONDecodeError:
    # Fallback to raw text parsing
    results = {"raw": output, "parsed": parse_text_output(output)}

Permission Denied

Problem: Cannot execute tools

Solution:

# Make tools executable
chmod +x /usr/local/bin/sherlock
chmod +x /opt/spiderfoot/sf.py

# Or run with Python explicitly
python -m sherlock username

Best Practices

1. Start with Fast Tools

Begin investigations with Holehe or Blackbird for quick results before running comprehensive scans.

2. Parallel Execution

Run multiple fast tools simultaneously:

"Run Sherlock and Blackbird in parallel for username 'target'"

3. Result Validation

Cross-reference findings from multiple tools for accuracy.

4. Timeout Management

• Fast tools (Holehe, Blackbird): 60-120 seconds
• Medium tools (Sherlock, Maigret): 300-600 seconds
• Slow tools (SpiderFoot): 1800-3600 seconds

5. Data Privacy

Always respect privacy laws and obtain proper authorization. Log all investigations for compliance.

Legal & Ethical Considerations

⚠️ CRITICAL: This tool is for legitimate security research and authorized investigations only.

• Only gather publicly available information
• Comply with GDPR, CCPA, and local privacy laws
• Respect platforms' Terms of Service
• Obtain written authorization for professional investigations
• Never use for stalking, harassment, or malicious purposes

Performance Tips

Optimize Sherlock:

# Target specific platforms
sherlock username --site Twitter Instagram GitHub

Optimize TheHarvester:

# Limit sources for speed
theharvester -d domain.com -b google,bing -l 100

Optimize Maigret:

# Disable slow sites
maigret username --timeout 10 --no-recursion

This skill enables AI coding agents to effectively assist developers in conducting OSINT investigations using multiple industry-standard tools through a unified MCP interface.