mcp-server-osint

An MCP (Model Context Protocol) server with comprehensive OSINT (Open Source Intelligence) tools for security research, threat intelligence, and digital investigations.

Features

This server provides a wide range of OSINT tools for:

• Domain & IP Investigation: DNS lookups, WHOIS queries, geolocation, reverse DNS
• Data Breach Checking: Have I Been Pwned integration
• Threat Intelligence: Shodan and VirusTotal scanning
• Search Tools: Google advanced operators and Maltego transform suggestions
• Person Search: Multi-platform individual searches

OSINT Tools

Domain & Network Tools

• dns_lookup: Perform DNS lookup for domains/IPs (A, AAAA, MX, TXT, NS, CNAME, SOA, ANY)
• whois_lookup: Perform WHOIS lookup for domains/IPs
• ip_geolocation: Get geolocation information for IP addresses
• subdomain_enumeration: Enumerate subdomains for a domain
• reverse_dns: Perform reverse DNS lookup (PTR) for IP addresses

Data Breach & Security Tools

• haveibeenpwned_check: Check if email addresses or domains have been compromised in data breaches
• shodan_search: Search Shodan for IP addresses, domains, or services (requires API key)
• virustotal_scan: Scan URLs, domains, IPs, or file hashes using VirusTotal (requires API key)

Search & Investigation Tools

• google_advanced_search: Construct Google search queries with advanced operators for OSINT research
• maltego_transform: Generate Maltego transform suggestions and queries for OSINT investigations
• name_search: Search for individuals across public records and platforms (GitHub, LinkedIn, Twitter, news, public records)

Basic Tools

• echo: Echo back a message
• add: Add two numbers together
• get_timestamp: Get current timestamp

Resources

• example://info: Server information
• example://version: Version information in JSON format

Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. (Optional) Set up API keys for enhanced functionality:

export SHODAN_API_KEY="your-shodan-api-key"
export VIRUSTOTAL_API_KEY="your-virustotal-api-key"
export HIBP_API_KEY="your-hibp-api-key"  # Optional, for higher rate limits

API Keys

Some tools require API keys for full functionality. See API_KEYS_SETUP.md for detailed setup instructions.

Quick Setup

Option 1: Environment Variables (Development)

export SHODAN_API_KEY="your-shodan-api-key"
export VIRUSTOTAL_API_KEY="your-virustotal-api-key"
export HIBP_API_KEY="your-hibp-api-key"  # Optional

Option 2: MCP Client Configuration (Recommended) Add to your MCP client config (e.g., ~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-server-osint": {
      "command": "node",
      "args": ["/path/to/mcp-server-basic/dist/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-key",
        "VIRUSTOTAL_API_KEY": "your-key",
        "HIBP_API_KEY": "your-key"
      }
    }
  }
}

API Key Requirements

• Shodan: Required for shodan_search - Get from https://account.shodan.io/
• VirusTotal: Required for virustotal_scan - Get from https://www.virustotal.com/gui/join-us
• Have I Been Pwned: Optional for haveibeenpwned_check - Get from https://haveibeenpwned.com/API/Key

For complete setup instructions, see API_KEYS_SETUP.md.

Usage

Running the Server

The server communicates via stdio (standard input/output):

npm start

Or after building:

node dist/index.js

Development

For development with auto-rebuild on changes:

npm run dev

MCP Client Configuration

To use this server with an MCP client (like Cursor), add it to your MCP configuration:

{
  "mcpServers": {
    "mcp-server-osint": {
      "command": "node",
      "args": ["/path/to/mcp-server-basic/dist/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key",
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key",
        "HIBP_API_KEY": "your-hibp-api-key"
      }
    }
  }
}

Or if using npm scripts:

{
  "mcpServers": {
    "mcp-server-osint": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/mcp-server-basic",
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key",
        "VIRUSTOTAL_API_KEY": "your-virustotal-api-key",
        "HIBP_API_KEY": "your-hibp-api-key"
      }
    }
  }
}

Tool Examples

Have I Been Pwned

Check if an email has been compromised:

{
  "name": "haveibeenpwned_check",
  "arguments": {
    "email": "user@example.com"
  }
}

Shodan Search

Search for services on a specific IP:

{
  "name": "shodan_search",
  "arguments": {
    "ip": "8.8.8.8"
  }
}

VirusTotal Scan

Scan a domain for threats:

{
  "name": "virustotal_scan",
  "arguments": {
    "domain": "example.com"
  }
}

Google Advanced Search

Construct a search query:

{
  "name": "google_advanced_search",
  "arguments": {
    "query": "security breach",
    "site": "example.com",
    "filetype": "pdf",
    "date_range": "2023-2024"
  }
}

Maltego Transform

Get transform suggestions:

{
  "name": "maltego_transform",
  "arguments": {
    "entity_type": "Domain",
    "value": "example.com"
  }
}

System Requirements

The OSINT tools require certain command-line utilities:

Required Tools:

• dig or nslookup: For DNS lookups (usually pre-installed on Linux/Mac)
• whois: For WHOIS queries

Installation:

macOS:

brew install whois

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install whois dnsutils

Linux (RHEL/CentOS):

sudo yum install whois bind-utils

Security & Legal Considerations

⚠️ Important Notes:

1. Legal Compliance: Only perform OSINT on targets you own or have explicit permission to investigate
2. Rate Limiting: API services have rate limits - respect them to avoid being blocked
3. API Keys: Store API keys securely in environment variables, never in code
4. Privacy Laws: Always respect privacy laws and terms of service when conducting investigations
5. Ethical Use: Use these tools responsibly and ethically

Project Structure

mcp-server-basic/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── README.md
└── OSINT_GUIDE.md        # Detailed OSINT tool guide

Documentation

For detailed information about each OSINT tool, see OSINT_GUIDE.md.

License

MIT