Maigret MCP Server

1# Maigret MCP Server
2[![smithery badge](https://smithery.ai/badge/mcp-maigret)](https://smithery.ai/server/mcp-maigret)
3 
4A Model Context Protocol (MCP) server for [maigret](https://github.com/soxoj/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](https://claude.ai).
5 
6<a href="https://glama.ai/mcp/servers/knnpcz651x"><img width="380" height="200" src="https://glama.ai/mcp/servers/knnpcz651x/badge" alt="mcp-maigret MCP server" /></a>
7 
8 
9## ⚠️ Warning
10 
11This tool is designed for legitimate OSINT research purposes. Please:
12- Only search for information that is publicly available
13- Respect privacy and data protection laws
14- Follow the terms of service of the platforms being searched
15- Use responsibly and ethically
16- Be aware that some sites may rate-limit or block automated searches
17 
18## Security
19 
20This server implements several security measures to prevent command injection attacks:
21 
22### Input Validation
23- **Usernames**: Only alphanumeric characters, underscores, hyphens, and periods are allowed (max 100 characters)
24- **URLs**: Must be valid HTTP/HTTPS URLs without shell metacharacters
25- **Tags**: Only alphanumeric characters, underscores, and hyphens are allowed
26 
27### Safe Command Execution
28- Uses `execFile()` instead of `exec()` to prevent shell interpolation
29- All command arguments are passed as arrays, not concatenated strings
30- Docker commands are executed without shell interpretation
31 
32### Reporting Security Issues
33If you discover a security vulnerability, please report it by opening an issue or contacting the maintainers directly. We take security seriously and will respond promptly.
34 
35## Requirements
36 
37- Node.js (v18 or later)
38- Docker
39- macOS, Linux, or Windows with Docker Desktop installed
40- Write access to the reports directory
41 
42## Quick Start
43 
44### Installing via Smithery
45 
46To install Maigret for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-maigret):
47 
48```bash
49npx -y @smithery/cli install mcp-maigret --client claude
50```
51 
52### Installing Manually
531. Install Docker:
54   - macOS: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
55   - Linux: Follow the [Docker Engine installation guide](https://docs.docker.com/engine/install/)
56 
572. Install the server globally via npm:
58```bash
59npm install -g mcp-maigret
60```
61 
623. Create a reports directory:
63```bash
64mkdir -p /path/to/reports/directory
65```
66 
674. Add to your Claude Desktop configuration file:
68```json
69{
70  "mcpServers": {
71    "maigret": {
72      "command": "mcp-maigret",
73      "env": {
74        "MAIGRET_REPORTS_DIR": "/path/to/reports/directory"
75      }
76    }
77  }
78}
79```
80 
81Configuration file location:
82- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
83- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
84 
855. Restart Claude Desktop
86 
87## Alternative Setup (From Source)
88 
89If you prefer to run from source or need to modify the code:
90 
911. Clone and build:
92```bash
93git clone <repository_url>
94cd mcp-maigret
95npm install
96npm run build
97```
98 
992. Add to your Claude Desktop configuration:
100```json
101{
102  "mcpServers": {
103    "maigret": {
104      "command": "node",
105      "args": ["/absolute/path/to/mcp-maigret/build/index.js"],
106      "env": {
107        "MAIGRET_REPORTS_DIR": "/path/to/reports/directory"
108      }
109    }
110  }
111}
112```
113 
114## Features
115 
116- **Username Search**: Search for a username across hundreds of social networks and websites
117- **URL Analysis**: Parse URLs to extract information and search for associated usernames
118- **Multiple Output Formats**: Support for txt, html, pdf, json, csv, and xmind formats
119- **Site Filtering**: Filter searches by site tags (e.g., photo, dating, us)
120- **Docker-based**: Reliable and consistent execution across environments
121 
122## Tools
123 
124### 1. Username Search Tool
125- Name: `search_username`
126- Description: Search for a username across social networks and sites
127- Parameters:
128  * `username` (required): Username to search for (alphanumeric, underscores, hyphens, periods only; max 100 chars)
129  * `format` (optional, default: "pdf"): Output format (txt, html, pdf, json, csv, xmind)
130  * `use_all_sites` (optional, default: false): Use all available sites instead of top 500
131  * `tags` (optional): Array of tags to filter sites (alphanumeric, underscores, hyphens only)
132 
133Example:
134```json
135{
136  "username": "test_user123",
137  "format": "html",
138  "use_all_sites": false,
139  "tags": ["photo"]
140}
141```
142 
143### 2. URL Analysis Tool
144- Name: `parse_url`
145- Description: Parse a URL to extract information and search for associated usernames
146- Parameters:
147  * `url` (required): URL to analyze
148  * `format` (optional, default: "pdf"): Output format (txt, html, pdf, json, csv, xmind)
149 
150Example:
151```json
152{
153  "url": "https://example.com/profile",
154  "format": "txt"
155}
156```
157 
158## Troubleshooting
159 
160### Docker Issues
161 
1621. Verify Docker is installed and running:
163```bash
164docker --version
165docker ps
166```
167 
1682. Check Docker permissions:
169   - Ensure your user has permissions to run Docker commands
170   - On Linux, add your user to the docker group: `sudo usermod -aG docker $USER`
171 
172### Reports Directory Issues
173 
1741. Verify the reports directory:
175   - The directory specified in MAIGRET_REPORTS_DIR must exist
176   - Your user must have write permissions to this directory
177   - Check permissions: `ls -la /path/to/reports/directory`
178 
1792. Common configuration mistakes:
180   - Missing MAIGRET_REPORTS_DIR environment variable
181   - Directory doesn't exist
182   - Incorrect permissions
183   - Trailing slashes in the path
184 
1853. After fixing any issues:
186   - Save the configuration file
187   - Restart Claude Desktop
188 
189## Error Messages
190 
191- "Docker is not installed or not running": Install Docker and start the Docker daemon
192- "MAIGRET_REPORTS_DIR environment variable must be set": Add the environment variable to your configuration
193- "Error creating reports directory": Check directory permissions and path
194- "Error executing maigret": Check Docker logs and ensure the container has proper permissions
195- "Invalid username": Username contains invalid characters. Use only alphanumeric, underscores, hyphens, and periods
196- "Invalid URL": URL is malformed or contains prohibited characters
197- "Invalid tag": Tag contains invalid characters. Use only alphanumeric, underscores, and hyphens
198 
199## Contributing
200 
2011. Fork the repository
2022. Create a feature branch (`git checkout -b feature/amazing-feature`)
2033. Commit your changes (`git commit -m 'Add amazing feature'`)
2044. Push to the branch (`git push origin feature/amazing-feature`)
2055. Open a Pull Request
206 
207## License
208 
209This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
210