mcp-maigret

mcp-maigret is an MCP server that lets AI agents run maigret, the OSINT tool that checks a username across thousands of sites. Ask your agent to find where a handle is registered, or to analyze a profile URL, and get a saved report back. Maigret runs in Docker, so there is nothing to install besides Docker and Node.

[!WARNING] Use this for legitimate, authorized OSINT research on publicly available information. Follow the law and each site's terms of service, and respect people's privacy. Some sites rate-limit or block automated lookups.

Highlights

• Username search across hundreds to thousands of sites, filterable by tag (photo, dating, us, ...).
• URL analysis. Hand it a profile URL and maigret extracts what it can and looks for linked usernames.
• Six report formats (txt, html, csv, json, xmind, pdf), saved to a directory you choose. See which ones work today.
• Hardened inputs. Strict validation and execFile with argument arrays. No shell is ever involved. See Security.
• Docker-based. The maigret image is pulled on first use, so every machine runs the same maigret.

How it works

flowchart LR
    A["AI agent<br/>(Claude Desktop, Claude Code, any MCP client)"] -->|"MCP over stdio"| S["mcp-maigret"]
    S -->|"validate input,<br/>execFile docker run"| D["soxoj/maigret<br/>(Docker)"]
    D -->|"checks sites"| W(("Public<br/>websites"))
    D -->|"writes report"| R[("MAIGRET_REPORTS_DIR")]
    S -->|"report path + scan output"| A

Quickstart

Requirements: Node.js 18 or newer, and Docker installed and running. Developed and tested on macOS. Linux and Windows (Docker Desktop) should work but are untested.

1. Pick a reports directory. The server saves reports here. It is created if missing. The variable is required.

export MAIGRET_REPORTS_DIR="$HOME/maigret-reports"

2. Add the server to your client.

claude mcp add maigret -e MAIGRET_REPORTS_DIR="$HOME/maigret-reports" -- npx -y mcp-maigret

Edit the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude Desktop:

{
  "mcpServers": {
    "maigret": {
      "command": "npx",
      "args": ["-y", "mcp-maigret"],
      "env": { "MAIGRET_REPORTS_DIR": "/absolute/path/to/maigret-reports" }
    }
  }
}

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

git clone https://github.com/w0h1v/mcp-maigret && cd mcp-maigret
npm install && npm run build

Then point your client at node /absolute/path/to/mcp-maigret/build/index.js with the same MAIGRET_REPORTS_DIR variable.

3. Try it. Ask your agent: "Use maigret to check where the username octocat is registered, filtered to the coding tag."

The first search pulls the maigret image (about 800 MB), so it takes longer.

Tools

search_username

Search for a username across social networks and sites.

{ "username": "octocat", "format": "html", "tags": ["coding"] }

The result contains the path of the saved report and maigret's console output. If the report file was not produced, the result says so instead of reporting success.

parse_url

Parse a URL to extract information and search for associated usernames.

{ "url": "https://github.com/octocat" }

Results come back as maigret's scan output text.

Output formats

Reports are written to MAIGRET_REPORTS_DIR. Maigret picks the file names, and for some formats it adds a suffix. When maigret finds related usernames it can write extra reports next to the main one (for example report_octocatsup.txt).

Statuses were checked against maigret 0.6.6 (image soxoj/maigret:latest, October 2026). Maigret's command line changes between releases, so this can drift.

Security

Usernames, URLs and tags come from an AI agent and are treated as untrusted.

• Validation. Usernames allow only [A-Za-z0-9_.-] (max 100 characters). Tags allow only [A-Za-z0-9_-] (max 50). URLs must parse as http or https and may not contain shell metacharacters.
• No shell. Docker is launched with execFile and an argument array, never a concatenated command string.
• Contained writes. Reports are written by the container into the single directory you mount. The server does not read or write elsewhere.

What this does not cover: the server runs Docker on your machine on your agent's behalf, and it makes network requests to many third-party sites from your IP address. Run it only for agents and clients you trust.

Found a vulnerability? Report it privately. See SECURITY.md.

Troubleshooting

More in the docs.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

• Changelog
• Questions and help: SUPPORT
• Security reports: SECURITY.md (private advisories, never public issues)

License

MIT. Independent project, not affiliated with the maigret project. Maigret is by soxoj and has its own license.