📌Overview

Purpose: To provide a Model Context Protocol (MCP) server for Maigret, enabling users to conduct open-source intelligence (OSINT) research on user accounts across various public platforms.

Overview: The Maigret MCP Server is a specialized tool that enhances the capabilities of the Maigret OSINT tool by facilitating comprehensive searches for usernames and URL analysis. It is compatible with MCP applications, making it a versatile addition for researchers and analysts in the field of cybersecurity and information gathering.

Key Features:

Username Search: Enables users to search for a given username across hundreds of social networks and websites, helping to gather extensive information about the online presence of an individual.
URL Analysis: Allows users to parse URLs, extracting valuable insights and identifying associated usernames, thereby enhancing the contextual understanding of web profiles.
Multiple Output Formats: Supports various output formats (txt, html, pdf, json, csv, and xmind), providing flexibility in how results are presented and utilized.
Site Filtering: Offers the ability to filter search results based on site tags, allowing for more targeted searches depending on the type of site (e.g., photo-sharing, dating).
Docker-based: Ensures reliable and consistent performance across different environments through the use of Docker, simplifying deployment and management.

Maigret MCP Server

A Model Context Protocol (MCP) server for maigret, a powerful OSINT tool that collects user account information from various public sources. This server provides tools for searching usernames across social networks and analyzing URLs. It is designed to integrate seamlessly with MCP-compatible applications like Claude Desktop.

⚠️ Warning

This tool is designed for legitimate OSINT research purposes. Please:

Only search for information that is publicly available
Respect privacy and data protection laws
Follow the terms of service of the platforms being searched
Use responsibly and ethically
Be aware that some sites may rate-limit or block automated searches

Requirements

Node.js (v18 or later)
Docker
macOS, Linux, or Windows with Docker Desktop installed
Write access to the reports directory

Quick Start

Installing via Smithery

To install Maigret for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-maigret --client claude

Installing Manually

Install Docker:
- macOS: Install Docker Desktop
- Linux: Follow the Docker Engine installation guide
Install the server globally via npm:

npm install -g mcp-maigret

Create a reports directory:

mkdir -p /path/to/reports/directory

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "maigret": {
      "command": "mcp-maigret",
      "env": {
        "MAIGRET_REPORTS_DIR": "/path/to/reports/directory"
      }
    }
  }
}

Configuration file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop

Alternative Setup (From Source)

If you prefer to run from source or need to modify the code:

Clone and build:

git clone <repository_url>
cd mcp-maigret
npm install
npm run build

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "maigret": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-maigret/build/index.js"],
      "env": {
        "MAIGRET_REPORTS_DIR": "/path/to/reports/directory"
      }
    }
  }
}

Features

Username Search: Search for a username across hundreds of social networks and websites
URL Analysis: Parse URLs to extract information and search for associated usernames
Multiple Output Formats: Support for txt, html, pdf, json, csv, and xmind formats
Site Filtering: Filter searches by site tags (e.g., photo, dating, us)
Docker-based: Reliable and consistent execution across environments

Tools

1. Username Search Tool

Name: search_username
Description: Search for a username across social networks and sites
Parameters:
- username (required): Username to search for
- format (optional, default: "pdf"): Output format (txt, html, pdf, json, csv, xmind)
- use_all_sites (optional, default: false): Use all available sites instead of top 500
- tags (optional): Array of tags to filter sites (e.g., ["photo", "dating"])

Example:

{
  "username": "test_user123",
  "format": "html",
  "use_all_sites": false,
  "tags": ["photo"]
}

2. URL Analysis Tool

Name: parse_url
Description: Parse a URL to extract information and search for associated usernames
Parameters:
- url (required): URL to analyze
- format (optional, default: "pdf"): Output format (txt, html, pdf, json, csv, xmind)

Example:

{
  "url": "https://example.com/profile",
  "format": "txt"
}

Troubleshooting

Docker Issues

Verify Docker is installed and running:

docker --version
docker ps

Check Docker permissions:
- Ensure your user has permissions to run Docker commands
- On Linux, add your user to the docker group: sudo usermod -aG docker $USER

Reports Directory Issues

Verify the reports directory:
- The directory specified in MAIGRET_REPORTS_DIR must exist
- Your user must have write permissions to this directory
- Check permissions: ls -la /path/to/reports/directory
Common configuration mistakes:
- Missing MAIGRET_REPORTS_DIR environment variable
- Directory doesn't exist
- Incorrect permissions
- Trailing slashes in the path
After fixing any issues:
- Save the configuration file
- Restart Claude Desktop

Error Messages

"Docker is not installed or not running": Install Docker and start the Docker daemon
"MAIGRET_REPORTS_DIR environment variable must be set": Add the environment variable to your configuration
"Error creating reports directory": Check directory permissions and path
"Error executing maigret": Check Docker logs and ensure the container has proper permissions

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.