Repository: BurtTheCoder/mcp-maigret Branch: main Commit: 1a7c9a4b1e4e Files: 10 Total size: 24.1 KB Directory structure: gitextract_km0eo5ii/ ├── .github/ │ └── workflows/ │ └── npm-publish.yaml ├── .gitignore ├── .npmignore ├── Dockerfile ├── LICENSE ├── README.md ├── package.json ├── smithery.yaml ├── src/ │ └── index.ts └── tsconfig.json ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/workflows/npm-publish.yaml ================================================ name: Publish to NPM on: push: branches: - main release: types: [created] jobs: build-and-publish: runs-on: ubuntu-latest permissions: contents: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 token: ${{ secrets.GITHUB_TOKEN }} - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' registry-url: 'https://registry.npmjs.org' - name: Configure Git run: | git config --local user.email "action@github.com" git config --local user.name "GitHub Action" - name: Install dependencies run: npm ci - name: Bump version if: github.event_name == 'push' && !contains(github.event.head_commit.message, '[skip ci]') run: | npm version patch -m "Bump version to %s [skip ci]" git push git push --tags - name: Build run: npm run build - name: Publish to NPM if: success() run: npm publish --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} ================================================ FILE: .gitignore ================================================ node_modules/ build/ *.log .env .env.local .env.*.local ================================================ FILE: .npmignore ================================================ # Source src/ # Development configs tsconfig.json .github/ .gitignore # Dependencies node_modules/ # IDE .vscode/ .idea/ # Logs *.log npm-debug.log* # Test files __tests__/ *.test.ts *.spec.ts # Other .DS_Store ================================================ FILE: Dockerfile ================================================ # Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile # Use the official Node.js 18 image as the base image FROM node:18-slim AS build # Set the working directory in the container WORKDIR /app # Copy package.json and package-lock.json to the working directory COPY package.json package-lock.json ./ # Install the project dependencies RUN npm install # Copy the rest of the application code COPY . . # Build the application RUN npm run build # Create a new stage for the production image FROM node:18-slim # Set the working directory in the container WORKDIR /app # Copy the built application from the build stage COPY --from=build /app/build /app/build COPY --from=build /app/package.json /app/package.json COPY --from=build /app/package-lock.json /app/package-lock.json # Install only production dependencies RUN npm ci --omit=dev # Set environment variable for the reports directory ENV MAIGRET_REPORTS_DIR=/app/reports # Create the reports directory RUN mkdir -p $MAIGRET_REPORTS_DIR # Expose the port on which the application will run EXPOSE 3000 # Command to run the application ENTRYPOINT ["node", "build/index.js"] ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2024 Burt The Coder Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ # Maigret MCP Server [![smithery badge](https://smithery.ai/badge/mcp-maigret)](https://smithery.ai/server/mcp-maigret) A 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). mcp-maigret MCP server ## ⚠️ 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 ## Security This server implements several security measures to prevent command injection attacks: ### Input Validation - **Usernames**: Only alphanumeric characters, underscores, hyphens, and periods are allowed (max 100 characters) - **URLs**: Must be valid HTTP/HTTPS URLs without shell metacharacters - **Tags**: Only alphanumeric characters, underscores, and hyphens are allowed ### Safe Command Execution - Uses `execFile()` instead of `exec()` to prevent shell interpolation - All command arguments are passed as arrays, not concatenated strings - Docker commands are executed without shell interpretation ### Reporting Security Issues If 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. ## 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](https://smithery.ai/server/mcp-maigret): ```bash npx -y @smithery/cli install mcp-maigret --client claude ``` ### Installing Manually 1. Install Docker: - macOS: Install [Docker Desktop](https://www.docker.com/products/docker-desktop) - Linux: Follow the [Docker Engine installation guide](https://docs.docker.com/engine/install/) 2. Install the server globally via npm: ```bash npm install -g mcp-maigret ``` 3. Create a reports directory: ```bash mkdir -p /path/to/reports/directory ``` 4. Add to your Claude Desktop configuration file: ```json { "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` 5. Restart Claude Desktop ## Alternative Setup (From Source) If you prefer to run from source or need to modify the code: 1. Clone and build: ```bash git clone cd mcp-maigret npm install npm run build ``` 2. Add to your Claude Desktop configuration: ```json { "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 (alphanumeric, underscores, hyphens, periods only; max 100 chars) * `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 (alphanumeric, underscores, hyphens only) Example: ```json { "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: ```json { "url": "https://example.com/profile", "format": "txt" } ``` ## Troubleshooting ### Docker Issues 1. Verify Docker is installed and running: ```bash docker --version docker ps ``` 2. 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 1. 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` 2. Common configuration mistakes: - Missing MAIGRET_REPORTS_DIR environment variable - Directory doesn't exist - Incorrect permissions - Trailing slashes in the path 3. 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 - "Invalid username": Username contains invalid characters. Use only alphanumeric, underscores, hyphens, and periods - "Invalid URL": URL is malformed or contains prohibited characters - "Invalid tag": Tag contains invalid characters. Use only alphanumeric, underscores, and hyphens ## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ================================================ FILE: package.json ================================================ { "name": "mcp-maigret", "version": "1.0.13", "description": "MCP server for maigret - OSINT username search across social networks", "main": "build/index.js", "type": "module", "bin": { "mcp-maigret": "build/index.js" }, "files": [ "build", "README.md", "LICENSE" ], "scripts": { "build": "tsc && chmod +x build/index.js", "prepublishOnly": "npm run build" }, "dependencies": { "@modelcontextprotocol/sdk": "^0.4.0" }, "devDependencies": { "@types/node": "^20.17.12", "typescript": "^5.0.0" }, "repository": { "type": "git", "url": "git+https://github.com/burtthecoder/mcp-maigret.git" }, "keywords": [ "mcp", "maigret", "osint", "social-networks", "username-search", "claude", "claude-desktop" ], "author": "Burt The Coder", "license": "MIT", "engines": { "node": ">=18" } } ================================================ FILE: smithery.yaml ================================================ # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml startCommand: type: stdio configSchema: # JSON Schema defining the configuration options for the MCP. type: object required: - maigretReportsDir properties: maigretReportsDir: type: string description: The directory where Maigret will store its reports. commandFunction: # A function that produces the CLI command to start the MCP on stdio. |- (config) => ({command: 'node', args: ['build/index.js'], env: {MAIGRET_REPORTS_DIR: config.maigretReportsDir}}) ================================================ FILE: src/index.ts ================================================ #!/usr/bin/env node import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js'; import { execFile } from 'child_process'; import { promisify } from 'util'; import { platform } from 'os'; import { existsSync, mkdirSync } from 'fs'; import { join } from 'path'; const execFileAsync = promisify(execFile); const DOCKER_IMAGE = 'soxoj/maigret:latest'; interface SearchUsernameArgs { username: string; format?: 'txt' | 'html' | 'pdf' | 'json' | 'csv' | 'xmind'; use_all_sites?: boolean; tags?: string[]; } interface ParseUrlArgs { url: string; format?: 'txt' | 'html' | 'pdf' | 'json' | 'csv' | 'xmind'; } interface ExecResult { stdout: string; stderr: string; } function sanitizeFilename(filename: string): string { return filename.replace(/[<>:"/\\|?*\x00-\x1F]/g, '_'); } /** * Validates username to prevent command injection. * Only allows alphanumeric characters, underscores, hyphens, and periods. */ function isValidUsername(username: string): boolean { // Max length check to prevent DoS if (username.length === 0 || username.length > 100) { return false; } // Only allow safe characters commonly found in usernames return /^[a-zA-Z0-9_.-]+$/.test(username); } /** * Validates URL to prevent command injection. * Must be a valid HTTP/HTTPS URL. */ function isValidUrl(urlString: string): boolean { try { const url = new URL(urlString); // Only allow http and https protocols if (url.protocol !== 'http:' && url.protocol !== 'https:') { return false; } // Check for suspicious characters that could be used for injection if (/[;&|`$(){}[\]<>\\]/.test(urlString)) { return false; } return true; } catch { return false; } } /** * Validates tags to prevent command injection. * Only allows alphanumeric characters, underscores, and hyphens. */ function isValidTag(tag: string): boolean { if (tag.length === 0 || tag.length > 50) { return false; } return /^[a-zA-Z0-9_-]+$/.test(tag); } function isSearchUsernameArgs(args: unknown): args is SearchUsernameArgs { if (!args || typeof args !== 'object') return false; const a = args as Record; return typeof a.username === 'string' && (a.format === undefined || ['txt', 'html', 'pdf', 'json', 'csv', 'xmind'].includes(a.format as string)) && (a.use_all_sites === undefined || typeof a.use_all_sites === 'boolean') && (a.tags === undefined || (Array.isArray(a.tags) && a.tags.every(t => typeof t === 'string'))); } function isParseUrlArgs(args: unknown): args is ParseUrlArgs { if (!args || typeof args !== 'object') return false; const a = args as Record; return typeof a.url === 'string' && (a.format === undefined || ['txt', 'html', 'pdf', 'json', 'csv', 'xmind'].includes(a.format as string)); } class MaigretServer { private server: Server; private reportsDir: string; constructor() { if (!process.env.MAIGRET_REPORTS_DIR) { throw new Error('MAIGRET_REPORTS_DIR environment variable must be set'); } this.reportsDir = process.env.MAIGRET_REPORTS_DIR; this.server = new Server({ name: 'maigret-server', version: '0.1.0', capabilities: { tools: {} }, timeout: 600000 // 10 minutes in milliseconds }); console.error('Using reports directory:', this.reportsDir); // Create reports directory if it doesn't exist if (!existsSync(this.reportsDir)) { console.error('Creating reports directory...'); mkdirSync(this.reportsDir, { recursive: true }); } this.setupToolHandlers(); this.server.onerror = (error) => console.error('[MCP Error]', error); process.on('SIGINT', async () => { await this.server.close(); process.exit(0); }); // Trigger setup immediately this.ensureSetup().catch(error => { console.error('Failed to setup maigret:', error); process.exit(1); }); } /** * Executes a command safely using execFile (no shell interpolation). * Arguments are passed as an array to prevent command injection. */ private async execCommand(cmd: string, args: string[]): Promise { console.error('Executing command:', cmd, args.join(' ')); try { const result = await execFileAsync(cmd, args, { maxBuffer: 10 * 1024 * 1024 }); console.error('Command output:', result.stdout); if (result.stderr) console.error('Command stderr:', result.stderr); return result; } catch (error) { console.error('Command failed:', error); throw error; } } private async ensureSetup(): Promise { try { console.error('Checking Docker...'); try { await this.execCommand('docker', ['--version']); } catch (error) { throw new Error('Docker is not installed or not running. Please install Docker and try again.'); } console.error('Checking if maigret image exists...'); try { await this.execCommand('docker', ['image', 'inspect', DOCKER_IMAGE]); console.error('Maigret image found'); } catch (error) { console.error('Maigret image not found, pulling...'); await this.execCommand('docker', ['pull', DOCKER_IMAGE]); console.error('Maigret image pulled successfully'); } } catch (error) { console.error('Setup failed:', error); throw error; } } private setupToolHandlers() { this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: 'search_username', description: 'Search for a username across social networks and sites', inputSchema: { type: 'object', properties: { username: { type: 'string', description: 'Username to search for' }, format: { type: 'string', enum: ['txt', 'html', 'pdf', 'json', 'csv', 'xmind'], description: 'Output format', default: 'pdf' }, use_all_sites: { type: 'boolean', description: 'Use all available sites instead of top 500', default: false }, tags: { type: 'array', items: { type: 'string' }, description: 'Filter sites by tags (e.g. photo, dating, us)', default: [] } }, required: ['username'] } }, { name: 'parse_url', description: 'Parse a URL to extract information and search for associated usernames', inputSchema: { type: 'object', properties: { url: { type: 'string', format: 'uri', description: 'URL to parse and analyze' }, format: { type: 'string', enum: ['txt', 'html', 'pdf', 'json', 'csv', 'xmind'], description: 'Output format', default: 'pdf' } }, required: ['url'] } } ] })); this.server.setRequestHandler(CallToolRequestSchema, async (request) => { try { await this.ensureSetup(); switch (request.params.name) { case 'search_username': { if (!isSearchUsernameArgs(request.params.arguments)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid arguments for search_username' ); } const { username, format = 'pdf', use_all_sites = false, tags = [] } = request.params.arguments; // Security: Validate username to prevent command injection if (!isValidUsername(username)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid username. Username must contain only alphanumeric characters, underscores, hyphens, and periods (max 100 characters).' ); } // Security: Validate all tags for (const tag of tags) { if (!isValidTag(tag)) { throw new McpError( ErrorCode.InvalidParams, `Invalid tag: "${tag}". Tags must contain only alphanumeric characters, underscores, and hyphens.` ); } } const safeUsername = sanitizeFilename(username); const reportPath = join(this.reportsDir, `report_${safeUsername}.${format}`); // Build docker command arguments (passed as array to prevent shell injection) const dockerArgs = [ 'run', '--rm', '-v', `${this.reportsDir}:/app/reports`, DOCKER_IMAGE, username, `--${format}`, '--no-color', '--no-progressbar', '-n', '200' ]; if (use_all_sites) { dockerArgs.push('-a'); } if (tags.length > 0) { dockerArgs.push('--tags', tags.join(',')); } // Run maigret in Docker using execFile (safe from shell injection) const { stdout, stderr } = await this.execCommand('docker', dockerArgs); return { content: [ { type: 'text', text: `Report saved to: ${reportPath}\n\n${stdout}${stderr ? `\nErrors:\n${stderr}` : ''}` } ] }; } case 'parse_url': { if (!isParseUrlArgs(request.params.arguments)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid arguments for parse_url' ); } const { url, format = 'pdf' } = request.params.arguments; // Security: Validate URL to prevent command injection if (!isValidUrl(url)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid URL. Must be a valid HTTP or HTTPS URL without special shell characters.' ); } // Build docker command arguments (passed as array to prevent shell injection) const dockerArgs = [ 'run', '--rm', '-v', `${this.reportsDir}:/app/reports`, DOCKER_IMAGE, '--parse', url, `--${format}`, '--no-color', '--no-progressbar', '--timeout', '60', '-n', '200' ]; // Run maigret in Docker using execFile (safe from shell injection) const { stdout, stderr } = await this.execCommand('docker', dockerArgs); return { content: [ { type: 'text', text: stdout + (stderr ? `\nErrors:\n${stderr}` : '') } ] }; } default: throw new McpError( ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}` ); } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: 'text', text: `Error executing maigret: ${errorMessage}` } ], isError: true }; } }); } async run() { const transport = new StdioServerTransport(); await this.server.connect(transport); console.error('Maigret MCP server running on stdio'); } } const server = new MaigretServer(); server.run().catch(console.error); ================================================ FILE: tsconfig.json ================================================ { "compilerOptions": { "target": "ES2020", "module": "ES2020", "moduleResolution": "node", "esModuleInterop": true, "outDir": "build", "rootDir": "src", "strict": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src/**/*"], "exclude": ["node_modules", "build"] }