Content
# 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.
