# StealthMole MCP Server

MCP (Model Context Protocol) server for accessing StealthMole threat intelligence API. Search and monitor threats across Deep & Dark Web through Claude and other MCP clients.

## Features

### 🔍 Comprehensive API Coverage

- **Darkweb Tracker (DT)**: Search Deep & Dark web content across 50+ indicators
- **Telegram Tracker (TT)**: Search Telegram channels, users, and messages
- **Credential Lookout (CL)**: Search leaked credentials from breaches
- **Compromised Data Set (CDS)**: Search infected device leaks from stealer malware
- **Combo Binder (CB)**: Search ID/Password combo leaks
- **ULP Binder (UB)**: Search URL-Login-Password format leaks
- **Ransomware Monitoring (RM)**: Monitor ransomware group breach incidents
- **Government Monitoring (GM)**: Monitor threats against government sector
- **Leaked Monitoring (LM)**: Monitor threats against enterprise sector
- **Management API**: Track API usage quotas

### 🔐 Authentication

- JWT-based authentication with HS256 signing
- Automatic token generation and management
- Secure session-level credential storage

## Prerequisites

- **Python**: 3.10 or higher
- **StealthMole API Credentials**: Get your access_key and secret_key from [StealthMole](https://stealthmole.com)
- **Smithery API key** (optional): For deployment at [smithery.ai/account/api-keys](https://smithery.ai/account/api-keys)

## Installation

### Development Setup

```bash
# Install dependencies
uv sync

# Run the server
uv run dev

# Test interactively
uv run playground
```

### Using with Claude Desktop

Add to your Claude Desktop configuration file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "stealthmole": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/stealthmole-mcp",
        "run",
        "start"
      ],
      "env": {
        "STEALTHMOLE_ACCESS_KEY": "your_access_key",
        "STEALTHMOLE_SECRET_KEY": "your_secret_key"
      }
    }
  }
}
```

Replace `/absolute/path/to/stealthmole-mcp` with the actual path to this directory.

## Available Tools

### Darkweb Tracker

#### `dt_search_targets`
Get list of searchable targets for an indicator
```
indicator: keyword, email, domain, ip, bitcoin, etc.
Returns: Available targets for the indicator
```

#### `dt_search_target`
Search for specific indicator and targets
```
indicator: Search type
targets: Comma-separated target list
text: Search query (supports AND, OR, NOT)
limit: Results limit (max: 100)
order_type: createDate or value
order: asc or desc
```

#### `dt_search_all`
Search across all targets for an indicator
```
indicator: Search type
text: Search query
limit: Results limit (max: 100)
```

#### `dt_search_by_id`
Get paginated results using search ID
```
search_id: ID from previous search
cursor: Pagination cursor
limit: Results limit (max: 100)
```

#### `dt_get_node_details`
Get detailed information for a node
```
node_id: Node ID from search results
parent_id: Optional parent node ID
data_from: Include data source list
include_url: Include URL list
include_contents: Include HTML source
```

### Telegram Tracker

#### `tt_search_targets`
Get searchable targets for Telegram indicator
```
indicator: keyword, telegram.channel, telegram.user, etc.
```

#### `tt_search_target`
Search Telegram for specific targets
```
indicator: Search type
targets: Comma-separated target list
text: Search query
limit: Results limit (max: 100)
```

#### `tt_get_node_details`
Get detailed Telegram node information
```
node_id: Node ID from search results
```

### Credential Lookout

#### `cl_search`
Search for leaked credentials
```
query: Search with indicators (domain:, email:, id:, password:, after:, before:)
limit: Results limit (max: 50)
cursor: Pagination cursor
start/end: UTC timestamp filters
```

Example queries:
- `domain:example.com` - All leaks for domain
- `email:user@example.com` - Specific email leaks
- `domain:example.com AND after:2024-01` - Recent leaks

### Compromised Data Set

#### `cds_search`
Search infected device leaks
```
query: Search with indicators (domain:, url:, email:, id:, password:, ip:, country:, after:, before:)
limit: Results limit (max: 50)
```

#### `cds_get_node_details`
Get detailed CDS information (requires Cyber Security Edition)
```
node_id: Node ID from search results
Returns: Stealer path, type, and full device info
```

### Combo Binder

#### `cb_search`
Search ID/Password combo leaks
```
query: Search with indicators (domain:, email:, id:, password:, after:, before:)
limit: Results limit (max: 50)
```

### ULP Binder

#### `ub_search`
Search URL-Login-Password format leaks
```
query: Search with indicators (domain:, url:, email:, id:, password:, after:, before:)
limit: Results limit (max: 50)
```

### Monitoring APIs

#### `rm_search` - Ransomware Monitoring
Monitor ransomware group breach incidents
```
query: Optional (torurl:, domain:) or empty for recent
limit: Results limit (max: 50)
order_type: detectionTime, victim, or attackGroup
```

#### `gm_search` - Government Monitoring
Monitor threats against government sector
```
query: Optional (url:, id:) or empty for recent
limit: Results limit (max: 50)
order_type: detectionTime, title, or author
```

#### `lm_search` - Leaked Monitoring
Monitor threats against enterprise sector
```
query: Optional (url:, id:) or empty for recent
limit: Results limit (max: 50)
```

### Management

#### `get_user_quotas`
Get API usage quotas for current month
```
Returns: Allowed and used queries per service
```

## Search Query Syntax

### Indicators

Darkweb Tracker supports 50+ indicators:

**Network**: domain, ip, tor, torurl, i2p, i2purl, url
**Identity**: email, id, tel, kssn
**Financial**: bitcoin, ethereum, monero, creditcard
**Files**: document, exefile, image, hash, blueprint
**Social**: facebook, twitter, instagram, telegram, discord
**Security**: cve, ioc, malware

### Operators

- **AND**: Both terms must be present
- **OR**: Either term must be present (max 3 per query)
- **NOT**: Exclude term from results
- **Max total**: 5 operators per query

### Examples

```
keyword search:
  "ransomware"

Indicator search:
  email:user@example.com
  domain:target.com
  bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

Combined operators:
  domain:example.com AND email:admin
  ip:192.168.1.1 OR ip:10.0.0.1
  domain:target.com AND NOT test

Time filters:
  domain:example.com AND after:2024-01
  email:admin AND before:2024-06-01
```

## Resources

The server provides built-in documentation resources:

- `stealthmole://api-info` - API overview and service information
- `stealthmole://indicators` - Complete list of Darkweb Tracker indicators

## Error Handling

Common API error codes:

- `401` - Invalid or expired token
- `400` - Invalid parameters (limit, cursor, etc.)
- `404` - Resource not found
- `422` - Bulk export required (>1M results)
- `426` - Query limit exceeded

## API Limits

- **Darkweb Tracker**: Max 100 results per request
- **Other APIs**: Max 50 results per request
- **Operators**: Max 3 OR, max 5 total per query
- **Bulk Export**: Contact support for >1M results

## Development

### Project Structure

```
stealthmole-mcp/
├── src/stealthmole_mcp/
│   ├── __init__.py
│   └── server.py          # Main server implementation
├── pyproject.toml         # Project configuration
└── README.md             # This file
```

### Running Tests

```bash
# Interactive testing
uv run playground

# Try example queries:
dt_search_targets(indicator="keyword")
cl_search(query="domain:example.com")
get_user_quotas()
```

## Deployment

### Deploy to Smithery

1. Push code to GitHub
2. Deploy at [smithery.ai/new](https://smithery.ai/new)
3. Configure with your StealthMole credentials

### Self-Hosting

Run the server directly:

```bash
# Production mode
uv run start

# Development mode with auto-reload
uv run dev
```

## Security Notes

⚠️ **Important**: Keep your API credentials secure

- Never commit credentials to version control
- Use environment variables or secure configuration
- Rotate keys regularly
- Monitor API usage for anomalies

## Support

- **StealthMole API Documentation**: [api.stealthmole.com](https://api.stealthmole.com)
- **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Smithery Platform**: [smithery.ai](https://smithery.ai)

## License

This MCP server implementation is provided as-is. StealthMole API access requires valid subscription and credentials.

## Version

Current version: 0.1.0 (November 2024)
Based on StealthMole API v2.2