# Sherlock MCP Server

An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the [Covertlabs](https://covertlabs.io) infostealer intelligence platform. Built with [FastMCP](https://github.com/jlowin/fastmcp).

## What is Sherlock?

Sherlock provides access to Covertlabs' comprehensive database of infostealer logs, enabling security researchers and threat intelligence teams to:

- **Search compromised credentials** by email, domain, username, or password
- **Investigate victims** by IP address, country, or stealer family
- **Retrieve detailed artifacts** including credentials, cookies, and browser history

## Features

- 🔍 **12 Search Tools** - Comprehensive search capabilities across the infostealer database
- 🔐 **Token Authentication** - Secure access via Personal Access Tokens
- ⚡ **Stateless HTTP** - Scalable, load-balancer friendly architecture
- 🐳 **Docker Ready** - Production-ready containerization

## Installation

### Prerequisites

- Python 3.11+
- A Covertlabs account with API access
- Your Personal Access Token from [app.covertlabs.io/cli/token](https://app.covertlabs.io/cli/token)

### Quick Start

```bash
# Clone the repository
git clone https://github.com/covertlabs/sherlock-mcp.git
cd sherlock-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python server.py
```

### Docker

```bash
docker compose up --build
```

## Configuration

Configure via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Server port |
| `HOST` | `0.0.0.0` | Server host |
| `COVERTLABS_API_URL` | `https://api.covertlabs.io` | API endpoint |
| `CORS_ORIGINS` | `*` | Allowed CORS origins |
| `LOG_REQUESTS` | `false` | Enable request logging |

## Client Configuration

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "sherlock": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "sherlock": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

## Available Tools

See the [docs/](docs/) folder for detailed documentation on each tool and response formats.

### Search Tools

| Tool | Description |
|------|-------------|
| `search_by_email` | Search victims by email address |
| `search_by_domain` | Search victims by domain |
| `search_by_ip` | Search victims by IP address |
| `search_by_username` | Search victims by username |
| `search_by_password` | Search victims by password |
| `search_text` | Broad text search across all fields |
| `search_by_country` | Search by ISO country code |
| `search_by_stealer` | Search by stealer malware family |

### Victim Detail Tools

| Tool | Description |
|------|-------------|
| `get_victim_profile` | Get victim profile and metadata |
| `get_victim_credentials` | Get stolen credentials |
| `get_victim_cookies` | Get stolen browser cookies |
| `get_victim_history` | Get browser history |

## Authentication

This server uses **Personal Access Token (PAT)** authentication. Tokens are passed through to the Covertlabs API.

1. Log in to [app.covertlabs.io](https://app.covertlabs.io)
2. Navigate to [CLI Token](https://app.covertlabs.io/cli/token)
3. Copy your token (format: `cl_pat_V1_...`)
4. Add to your MCP client configuration

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Server information |
| `/health` | GET | Health check |
| `/mcp` | POST | MCP protocol endpoint |

## Documentation

- [Tools Reference](docs/tools.md) - Detailed tool documentation
- [Response Formats](docs/responses.md) - API response schemas
- [Examples](docs/examples.md) - Usage examples

## Support

- **Documentation**: [docs.covertlabs.io](https://docs.covertlabs.io)
- **Issues**: [GitHub Issues](https://github.com/covertlabs/sherlock-mcp/issues)
- **Email**: support@covertlabs.io

## License

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