Skip to main content
Glama
Sign In
enesjakozh
mcp-maigret

mcp-maigret

by w0h1v
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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.

Related MCP server: Maigret MCP Server

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, plus either Docker installed and running, or maigret installed locally (pipx install 'maigret[pdf]'). MAIGRET_RUNNER chooses docker, local or auto (default: local if maigret is on PATH, else Docker); see Connect a client. 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" }
    }
  }
}
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.

Parameter

Type

Default

Description

username

string, required

Letters, digits, _, - and . only, up to 100 characters

format

enum

txt

txt, html, csv, json, xmind or pdf (see formats)

use_all_sites

boolean

false

Check all sites in maigret's database instead of the top 500

tags

string[]

none

Only check sites with these tags. Letters, digits, _ and - only

{ "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.

Parameter

Type

Default

Description

url

string, required

An http or https URL without shell metacharacters

format

enum

txt

Same options as above

{ "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).

Format

File written by search_username

Status

txt

report_<username>.txt

Works. Default.

csv

report_<username>.csv

Works

json

report_<username>_simple.json

Works

html

report_<username>_plain.html

Works

xmind

report_<username>.xmind

Works

pdf

report_<username>.pdf

Works with a local maigret installed with the pdf extra, and in this repo's Docker image. Not available with the stock soxoj/maigret image used by the Docker runner; the tool reports that no file was produced.

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

Message

Fix

Docker is not installed or not running

Install Docker and start the daemon. Check with docker --version and docker ps. On Linux, add yourself to the docker group: sudo usermod -aG docker $USER.

MAIGRET_REPORTS_DIR environment variable must be set

Add the variable to your client's env block, then restart the client.

Error creating reports directory

Check the path and that your user can write to it. Use an absolute path without a trailing slash.

Invalid username / Invalid tag / Invalid URL

Input failed validation. Use only the characters listed under Tools.

No report file was produced ...

The chosen format isn't available in the image (see formats). Try txt, json or html.

Error executing maigret

Read the Docker output included in the message. Often a network problem or a changed maigret option.

Searches seem slow

The first run pulls the image. Narrow the search with tags, and avoid use_all_sites unless you need it.

More in the docs.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

License

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

Available Tools

2 tools
parse_urlC

Parse a URL to extract information and search for associated usernames

NameRequiredDescriptionDefault
urlYesURL to parse and analyze
formatNoOutput formattxt

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It does not state whether this is a read-only operation, whether it fetches network content, whether authentication is required, or what side effects the username search may have.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no redundant text. Its brevity is appropriate, though the phrase 'extract information' is under-specified rather than wastefully verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This tool has two parameters, no annotations, and no output schema, so the description needs to explain more about behavior and scope. It omits what information is extracted, what the username search returns, and how the output format choice affects results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already explains both the URL and output format parameters. The description does not add any details about URL formats, supported schemes, or how the format enum affects behavior, so it remains at the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource, 'Parse a URL,' but qualifies it with the vague phrase 'extract information' without saying what information. It also mentions searching for associated usernames, which blurs the boundary with the sibling search_username tool rather than clearly distinguishing this tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use parse_url versus search_username or when not to use it. The phrase about searching for associated usernames hints at overlapping use cases but does not resolve which tool should be selected.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_usernameB

Search for a username across social networks and sites

NameRequiredDescriptionDefault
tagsNoFilter sites by tags (e.g. photo, dating, us)
formatNoOutput formattxt
usernameYesUsername to search for
use_all_sitesNoUse all available sites instead of top 500

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full behavioral burden and does not meet it. It never says the tool scans hundreds of sites (a slow, network-heavy operation), that output is written as a report file whose type is chosen by the format parameter, or anything about reliability or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence with no filler, so nothing is wasted. However, for a tool with four parameters and file-generation behavior, this level of terseness is arguably under-sized rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description is the only place an agent could learn what calling this actually produces. It omits that results arrive as a formatted report artifact and says nothing about scope or duration, leaving a meaningful gap for a multi-parameter search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters including the tags and format enums are already documented in the schema. The description adds no extra meaning beyond that, which makes the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('Search for a username') plus scope ('across social networks and sites'), which is materially clearer than the bare name. It does not distinguish itself from the only sibling, parse_url, though those two tools are different enough in kind that confusion is unlikely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer it should call this when it has a username to trace. There is no guidance on when not to use it, no mention of cost/time tradeoffs for the use_all_sites toggle, and no explanation of when tag filtering is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.20
    • First observedparse_url
    • First observedsearch_username
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation4/5

The two tools have distinct primary inputs: a username versus a URL. However, parse_url also searches for associated usernames, creating some overlap with search_username that could cause an agent to hesitate when starting from a URL.

Naming Consistency5/5

Both tools use a clean, consistent snake_case verb_noun pattern: search_username and parse_url. The convention is predictable and easy to scan.

Tool Count3/5

Two tools is thin for an OSINT username/URL search server, though it may reflect a narrow wrapper around Maigret. It is borderline rather than clearly mismatched.

Completeness3/5

The surface covers basic username searching and URL parsing, but lacks obvious supporting operations such as listing supported sites, retrieving structured results, or exporting reports. Agents may hit dead ends when they need more than a raw search.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • Maigret MCP Server

    mikeysrecipes
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables OSINT research by searching usernames across hundreds of social networks and websites, and analyzing URLs to extract information and find associated usernames using the Maigret tool.
    547 npm
    MIT

  • OSINT MCP Server

    CloudWaddie
    A
    license
    D
    quality
    D
    maintenance
    A comprehensive MCP server providing tools for IP, domain, email, and image-based open-source intelligence. It integrates services like Shodan, VirusTotal, and HaveIBeenPwned to facilitate advanced security research and data gathering.
    56
    40 npm
    ISC

  • OSINT Tools MCP Server

    frishtik
    A
    license
    Not graded
    quality
    D
    maintenance
    A comprehensive MCP server that exposes multiple OSINT tools to AI assistants like Claude, enabling sophisticated reconnaissance and information gathering tasks using industry-standard OSINT tools.
    247
    MIT

Appeared in Searches