Sherlock MCP Server

FastMCP server integration for the Sherlock OSINT tool – Seamlessly search social media accounts across 400+ platforms using the Model Context Protocol. Perfect for OSINT researchers, cybersecurity professionals, and AI assistants performing username enumeration and open-source intelligence gathering.

Mission

This project is built with a commitment to finding truth and countering propaganda through ethical open-source intelligence. In an era of misinformation and digital manipulation, we believe in empowering investigators, journalists, and truth-seekers with transparent, verifiable tools for social media reconnaissance.

Our mission is to:

• Promote Truthful Investigation: Provide reliable tools for fact-checking and source verification
• Counter Propaganda: Enable systematic analysis of online narratives and account authenticity
• Maintain Ethical Standards: Ensure all usage aligns with privacy rights and responsible disclosure
• Foster Transparency: Open-source development for community scrutiny and improvement

Read our full Mission Statement for detailed principles and applications.

Features

• Username Search: Find social media profiles associated with a username
• Structured Output: Returns formatted results with site names, URLs, and existence status
• Error Handling: Graceful handling of missing dependencies, timeouts, and failures
• Ethical Use: Designed for responsible OSINT investigations
• MCP Integration: Native support for Model Context Protocol in AI workflows

Demo

Experience the power of OSINT username searching with this MCP server. Connect to your favorite MCP-compatible AI assistant and query social media presence instantly.

Placeholder for demo GIF or screenshot – coming soon!

Prerequisites

• Python 3.13+
• Sherlock CLI tool installed: pipx install sherlock-project

Docker Setup

For containerized deployment using the official Sherlock Docker image:

1. Build the Docker image:

   docker build -t sherlock-mcp .
   

2. Run the container:

   docker run -it sherlock-mcp
   

This starts the MCP server inside the container. Connect MCP clients via stdio pipes or configure HTTP transport for remote access.

Installation

1. Clone this repository:

   git clone <repo-url>
   cd sherlock-mcp
   

2. Install dependencies:

   pip install -e .
   

3. Ensure Sherlock is installed:

   pipx install sherlock-project
   

Usage

Running the Server

python main.py

This starts the MCP server with stdio transport, ready for MCP clients.

Example MCP Client Usage

When connected to an MCP-compatible client (e.g., Claude Desktop), use the search_username tool:

Tool: search_username
Arguments: {"username": "exampleuser"}

Response:

{
  "found": [
    {"site": "github", "url": "https://github.com/exampleuser", "exists": true},
    {"site": "twitter", "url": "https://twitter.com/exampleuser", "exists": true}
  ],
  "total_found": 2,
  "error": null
}

Tool Reference

search_username(username: str)

Searches for social media accounts associated with the given username.

Parameters:

• username (str): The username to search for

Returns:

• found (list): Array of found profiles with site, URL, and exists status
• total_found (int): Number of profiles found
• error (str): Error message if any (null on success)

Contributing

We welcome contributions to enhance this OSINT MCP server! Whether it's bug fixes, new features, or documentation improvements, your input helps the cybersecurity and AI communities.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guidelines for more details.

Ethical Considerations

This tool is designed for truth-seeking and countering propaganda, but with great power comes great responsibility. Always use ethically and legally.

General Guidelines

• Use only for legitimate OSINT purposes
• Respect platform terms of service
• Be aware of privacy implications
• Consider rate limiting to avoid overwhelming services

Countering Propaganda Best Practices

• Cross-Reference Sources: Verify account authenticity across multiple platforms
• Check Creation Dates: New accounts may indicate coordinated campaigns
• Analyze Patterns: Look for coordinated posting behaviors or similar content
• Respect Privacy: Focus on public information and avoid doxxing
• Fact-Check Results: Use additional verification tools for claims
• Document Methodology: Maintain transparency in investigative processes
• Avoid Harm: Do not use findings to harass or intimidate individuals

Responsible Usage

• Obtain proper authorization for investigations
• Comply with local laws and regulations
• Use findings to promote truth and accountability
• Share results responsibly to avoid contributing to misinformation

Troubleshooting

• Sherlock not found: Install with pipx install sherlock-project
• Timeout errors: Increase timeout in code or use smaller username sets
• No results: Username may not exist on searched platforms

License

MIT License