npm package: @superadnim/osint-mcp-server
Description: Professional OSINT MCP Server for intelligence gathering with privacy protection
Author: OSINT Tools
Latest version: 1.0.5

# OSINT MCP Server

A professional-grade OSINT (Open Source Intelligence) MCP server that provides comprehensive intelligence gathering capabilities with strong privacy protection and ethical guidelines.

## Features

### 🔍 Intelligence Gathering Tools
- **People Search**: Multi-source people search with demographic intelligence
- **Phone Lookup**: Comprehensive phone number intelligence including carrier, location, and spam analysis
- **Email Intelligence**: Email analysis including breach data and account enumeration
- **Username Enumeration**: Systematic username discovery across platforms
- **Domain Reconnaissance**: DNS analysis, WHOIS, and subdomain enumeration
- **Google Dorking**: Advanced search engine reconnaissance
- **Investigation Mind Maps**: Visual investigation workflow organization

### 🔒 Privacy & Security
- **Privacy Protection**: Automatic redaction of sensitive information (SSN, financial data)
- **GDPR/CCPA Compliance**: Built-in compliance with privacy regulations
- **Data Retention**: Configurable data retention policies
- **Audit Logging**: Comprehensive audit trail of all activities
- **Rate Limiting**: Respectful API usage with configurable rate limits

### 🏗️ Architecture
- **Three-Tier OSINT Methodology**: Basic → Intermediate → Advanced intelligence gathering
- **Modular Data Sources**: Pluggable architecture for different intelligence sources
- **Correlation Engine**: Cross-reference and validate data from multiple sources
- **Caching System**: Intelligent caching to reduce API calls and improve performance
- **Error Handling**: Robust error handling and fallback mechanisms

## Installation

### Global Installation
```bash
npm install -g @superadnim/osint-mcp-server
```

### NPX Usage
```bash
npx @superadnim/osint-mcp-server
```

### Local Project
```bash
npm install @superadnim/osint-mcp-server
```

## MCP Client Integration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "osint": {
      "command": "npx",
      "args": ["@superadnim/osint-mcp-server"],
      "env": {
        "OSINT_API_TIMEOUT": "30000",
        "OSINT_RATE_LIMIT_ENABLED": "true"
      }
    }
  }
}
```

## Environment Variables

### API Configuration
```bash
OSINT_API_TIMEOUT=30000                    # API request timeout in milliseconds
OSINT_RATE_LIMIT_ENABLED=true             # Enable rate limiting
OSINT_MAX_CONCURRENT_REQUESTS=5           # Maximum concurrent requests

# Data Retention
OSINT_DATA_RETENTION_HOURS=24             # Data retention in hours
OSINT_INVESTIGATION_TTL=168               # Investigation TTL in hours (7 days)

# Privacy Settings
OSINT_REDACT_SSN=true                     # Redact Social Security Numbers
OSINT_REDACT_FINANCIAL=true              # Redact financial information
OSINT_GDPR_COMPLIANCE=true               # Enable GDPR compliance

# Logging
OSINT_LOG_LEVEL=info                      # Log level (debug, info, warn, error)
OSINT_STRUCTURED_LOGGING=true            # Enable structured JSON logging
OSINT_AUDIT_ENABLED=true                 # Enable audit logging
```

### API Keys (Optional for Enhanced Features)
```bash
HAVEIBEENPWNED_API_KEY=your_key_here
SHODAN_API_KEY=your_key_here
VIRUSTOTAL_API_KEY=your_key_here
HUNTER_IO_API_KEY=your_key_here
NUMVERIFY_API_KEY=your_key_here
```

## Available Tools

### 1. osint_people_search
Search for people using name, email, or phone across multiple sources.

```json
{
  "query": "John Doe",
  "search_type": "name",
  "include_relatives": false,
  "include_addresses": true,
  "confidence_threshold": 0.3,
  "max_results": 10
}
```

### 2. osint_phone_lookup
Lookup phone number information including carrier and location data.

```json
{
  "phone": "+1234567890",
  "include_carrier": true,
  "include_location": true,
  "include_spam_check": true
}
```

### 3. osint_email_intel
Analyze email addresses for breaches and account enumeration.

```json
{
  "email": "example@domain.com",
  "check_breaches": true,
  "enumerate_accounts": false,
  "analyze_domain": true
}
```

### 4. osint_username_enum
Enumerate username across social media platforms.

```json
{
  "username": "johndoe123",
  "platforms": ["twitter", "instagram", "linkedin"],
  "include_profiles": false,
  "max_concurrent": 10
}
```

### 5. osint_domain_recon
Perform comprehensive domain reconnaissance.

```json
{
  "domain": "example.com",
  "include_subdomains": false,
  "include_dns_records": true,
  "include_whois": true
}
```

### 6. osint_google_dorking
Advanced Google dorking and search engine reconnaissance.

```json
{
  "query": "site:example.com filetype:pdf",
  "dork_type": "custom",
  "max_results": 10
}
```

### 7. osint_create_mind_map
Create and manage investigation mind maps.

```json
{
  "investigation_id": "inv-123",
  "action": "create",
  "name": "Investigation Alpha"
}
```

## Privacy and Ethics

This tool is designed for **defensive security purposes only**. Users must:

- Only investigate entities they have explicit permission to research
- Comply with all applicable laws and regulations
- Respect privacy and data protection rights
- Use the tool ethically and responsibly
- Not use the tool for harassment, stalking, or malicious purposes

### Built-in Privacy Protection
- Automatic redaction of sensitive personal information
- Configurable data retention policies
- GDPR/CCPA compliance features
- Audit logging for accountability
- No persistent storage of personal data

## Development

### Prerequisites
- Node.js >= 18.0.0
- NPM >= 8.0.0

### Setup
```bash
git clone <repository>
cd osint-mcp-server
npm install
```

### Build
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Testing
```bash
npm test
npm run test:coverage
```

### Linting
```bash
npm run lint
npm run lint:fix
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Disclaimer

This software is provided for educational and defensive security purposes only. Users are responsible for ensuring their use complies with all applicable laws and regulations. The authors are not responsible for any misuse of this tool.

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## Support

For issues and questions:
- GitHub Issues: [Create an issue](https://github.com/osint-tools/mcp-server/issues)
- Documentation: [Full documentation](docs/)

---

**⚠️ Important**: Always use this tool responsibly and in compliance with applicable laws and ethical guidelines.