Maigret MCP Endpoint

This Model Context Protocol (MCP) service encapsulates the functionality of maigret, an advanced Open Source Intelligence (OSINT) framework. It is engineered to systematically gather registration details tied to specific user identities across numerous web domains and to perform forensic decomposition of URLs to uncover embedded identity markers. It offers smooth interoperability with MCP-aware client software, such as Claude Desktop.

⚠️ Usage Advisory

This instrument is intended strictly for lawful, sanctioned reconnaissance operations. Adherence to the following is mandatory: - Restrict queries to data ascertainable through public channels. - Uphold all established privacy conventions and data governance statutes. - Observe the stipulated terms of service for all queried platforms. - Exercise responsible, ethical deployment. - Acknowledge the potential for service throttling or automated access mitigation by remote hosts.

Prerequisites

• A runtime environment supporting Node.js (version 18 or higher)
• Docker containerization utility
• Compatibility with macOS, Linux, or Windows (requiring Docker Desktop)
• Write permissions for the designated report storage volume

Rapid Deployment Guide

Automated Installation via Smithery

For immediate integration with Claude Desktop using Smithery:

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

Manual Setup Procedure

1. Establish Docker:
2. For Apple Silicon/macOS: Secure Docker Desktop

3. For Linux: Adhere to the official Docker Engine installation guide

4. Install the server executable globally via npm: bash npm install -g mcp-maigret

5. Provision a location for artifact storage: bash mkdir -p /path/to/reports/directory

6. Integrate into your Claude Desktop configuration file (claude_desktop_config.json):

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

Configuration file system paths: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Initiate a relaunch of the Claude Desktop application.

Source Code Execution Path

For scenarios requiring direct execution from the source repository or modification of the underlying code:

1. Obtain and compile the source: bash git clone cd mcp-maigret npm install npm run build

2. Update the Claude Desktop configuration to reference the compiled output:

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

Core Capabilities

• Identity Probe: Execute searches for a specific handle across hundreds of digital venues.
• URI Forensics: Analyze Uniform Resource Identifiers to distill user metadata.
• Output Versatility: Native support for generating artifacts in txt, html, pdf, json, csv, and xmind formats.
• Platform Scoping: Employ site categorization tags (e.g., 'dating', 'image sharing') to narrow investigation scope.
• Containerized Operation: Leverages Docker for predictable, environment-agnostic execution.

Available Operations

1. Identity Search Operation

• Operation Name: search_username
• Synopsis: Systematically probes social platforms for a given user identifier.
• Parameters:
• username (Mandatory): The unique identifier sought.
• format (Optional, Default: "pdf"): Desired output serialization format (txt, html, pdf, json, csv, xmind).
• use_all_sites (Optional, Default: false): Flag to engage the complete site registry instead of the default top 500.
• tags (Optional): A list of conceptual tags to restrict the search domain (e.g., ["dating", "media"]).

Example Payload:

{ "username": "shadow_agent_01", "format": "json", "use_all_sites": true, "tags": ["finance"] }

2. URI Decomposition Operation

• Operation Name: parse_url
• Synopsis: Deconstructs a provided URI to extract intrinsic data elements and associated user affiliations.
• Parameters:
• url (Mandatory): The web address targeted for analysis.
• format (Optional, Default: "pdf"): Output format specification (txt, html, pdf, json, csv, xmind).

Example Payload:

{ "url": "https://forum.securenet.org/user/observer_x", "format": "csv" }

Troubleshooting Common Anomalies

Docker Environment Issues

1. Confirm Docker service status: bash docker --version docker ps

2. Validate user permissions (especially on Linux):

3. Ensure the executing user belongs to the 'docker' group: sudo usermod -aG docker $USER (Requires re-login/new shell session).

Artifact Repository Access Problems

1. Confirmation of target directory existence and accessibility:
2. The path specified by MAIGRET_REPORTS_DIR must be present.

3. Verify read/write permissions: ls -ld /path/to/reports/directory

4. Frequent configuration oversights:

5. Omission of the required MAIGRET_REPORTS_DIR variable.
6. Path resolution errors or incorrect segmentation.

7. Insufficient filesystem permissions.

8. Remediation cycle:

9. Rectify the underlying constraint.
10. Re-apply configuration changes.
11. Restart the client application (Claude Desktop).

Reported Failure Indicators

• "Docker is not installed or not running": Installation or activation of the Docker daemon is necessary.
• "MAIGRET_REPORTS_DIR environment variable must be set": Define this variable within the server configuration block.
• "Error creating reports directory": Investigate filesystem access rights for the specified location.
• "Error executing maigret": Review Docker container logs for internal execution failures or permission denials within the container.

Collaborative Development

1. Fork the primary repository.
2. Branch for new work: (git checkout -b enhancement/new-feature)
3. Stage and commit modifications: (git commit -m 'Implement feature enhancement')
4. Propagate changes: (git push origin enhancement/new-feature)
5. Submit a formal Pull Request.

Licensing

This software is distributed under the terms of the MIT License; refer to the accompanying LICENSE documentation for specifics.