Sherlock Server

An official Model Context Protocol (MCP) server for the Covertlabs infostealer intelligence platform. Built with 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

Quick Start

# 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

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:

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

Claude Desktop

Add to your Claude Desktop MCP configuration:

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

Available Tools

See the 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
2. Navigate to 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 - Detailed tool documentation
• Response Formats - API response schemas
• Examples - Usage examples

Support

• Documentation: docs.covertlabs.io
• Issues: GitHub Issues
• Email: [email protected]

License

MIT License - see LICENSE for details.