🕵️♂️ (2-in-1) Email & Username OSINT suite featuring native MCP support for deep data extraction just from a single Email/Username. Analyzes 2720+ actively maintained scan vectors (210+ email / 2510+ username) for security research, investigations, and digital footprinting.
Python cybersecuritycybersecurity-toolsemail-osintethical-hackingethical-hacking-toolsidentificationinfosecosintosint-emailosint-toolosint-toolsosint-usernamepentestingpythonredteam-toolsredteamingthreat-intelligence
feat: add Model Context Protocol (MCP) server support
Kaifb61ce4dd155c
diff --git a/.github/workflows/lint-pr.yml b/.github/workflows/lint-pr.ymlindex 464a563..614eb1f 100644--- a/.github/workflows/lint-pr.yml+++ b/.github/workflows/lint-pr.yml@@ -25,7 +25,7 @@ jobs:- name: Install lintersrun: |python -m pip install --upgrade pip- pip install httpx curl_cffi colorama types-colorama rich+ pip install httpx curl_cffi colorama types-colorama rich mcppip install ruff==0.15.22 mypy- name: Run ruffdiff --git a/.github/workflows/lint-push.yml b/.github/workflows/lint-push.ymlindex 9b8d5e7..bbae2b7 100644--- a/.github/workflows/lint-push.yml+++ b/.github/workflows/lint-push.yml@@ -26,7 +26,7 @@ jobs:- name: Install lintersrun: |python -m pip install --upgrade pip- pip install httpx curl_cffi colorama types-colorama rich+ pip install httpx curl_cffi colorama types-colorama rich mcppip install ruff==0.15.22 mypy- name: Run ruffdiff --git a/pyproject.toml b/pyproject.tomlindex 227cf5e..611e879 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -26,12 +26,14 @@ keywords = ["osint", "email-osint", "username-osint", "python", "cli-tool", "cyb[project.optional-dependencies]dev = ["pytest", "pytest-cov", "pytest-anyio", "anyio[trio]"]pdf = ["reportlab>=4.0.0", "pillow>=10.0.0", "svglib>=1.5.0"]+mcp = ["mcp>=1.2.0"][project.urls]Homepage = "https://github.com/kaifcodec/user-scanner"[project.scripts]user-scanner = "user_scanner.__main__:main"+user-scanner-mcp = "user_scanner.mcp.server:main"[tool.flit.module]name = "user_scanner"diff --git a/user_scanner/mcp/__init__.py b/user_scanner/mcp/__init__.pynew file mode 100644index 0000000..ba50c40--- /dev/null+++ b/user_scanner/mcp/__init__.py@@ -0,0 +1 @@+"""MCP (Model Context Protocol) server for user-scanner."""diff --git a/user_scanner/mcp/handlers.py b/user_scanner/mcp/handlers.pynew file mode 100644index 0000000..5053545--- /dev/null+++ b/user_scanner/mcp/handlers.py@@ -0,0 +1,126 @@+import asyncio+import json+import logging+import mcp.types as types+from typing import Any++from user_scanner.core import engine+from user_scanner.core.formatter import into_json+from user_scanner.core.helpers import find_module, load_categories, load_modules, get_site_name, ScanConfig, set_proxy_manager, set_global_timeout+from user_scanner.core.cross_scan import run_cross_scan, CrossScanConfig+from user_scanner.core.orchestrator import set_concurrency as set_user_concurrency+from user_scanner.core.email_orchestrator import set_concurrency as set_email_concurrency++logger = logging.getLogger("user-scanner-mcp")++async def execute_scan(arguments: dict, is_email: bool) -> list[types.TextContent]:+ target_key = "email" if is_email else "username"+ target = arguments.get(target_key)++ if not target:+ raise ValueError(f"Missing '{target_key}' argument")++ category = arguments.get("category")+ module_name = arguments.get("module")+ allow_loud = arguments.get("allow_loud", False)+ no_nsfw = arguments.get("no_nsfw", False)+ proxies = arguments.get("proxies")++ if proxies:+ logger.info(f"Setting up proxy manager with {len(proxies)} proxies.")+ set_proxy_manager(proxies=proxies)+ else:+ # Clear it just in case this is a subsequent request+ set_proxy_manager(proxies=None)++ timeout = arguments.get("timeout")+ if timeout is not None:+ set_global_timeout(float(timeout))+ else:+ set_global_timeout(None) # type: ignore++ concurrency = arguments.get("concurrency")+ if concurrency is not None:+ set_user_concurrency(int(concurrency))+ set_email_concurrency(int(concurrency))++ cross_scan = arguments.get("cross_scan", False)+ cross_links = arguments.get("cross_links", "all")+ cross_emails = arguments.get("cross_emails", "verified")+ cross_depth = arguments.get("cross_depth", 1)+ cross_sweep = arguments.get("cross_sweep", 3)++ if category and module_name:+ raise ValueError("Cannot specify both 'category' and 'module'. Choose one.")++ logger.info(f"Executing {'email' if is_email else 'username'} scan for: {target}")++ # Construct base config+ config = ScanConfig(allow_loud=allow_loud, no_nsfw=no_nsfw, timeout=timeout)++ # 1. Run Initial Scan+ results = []+ if module_name:+ modules = find_module(module_name, is_email=is_email, no_nsfw=no_nsfw)+ if not modules:+ return [types.TextContent(type="text", text=f"Error: Module '{module_name}' not found.")]+ # For simplicity in MCP, we just use engine.check which ignores loud checks if directly targeted+ # But to be safe, we just run the first module+ result = await engine.check(modules[0], target)+ results = [result]+ elif category:+ try:+ results = await engine.check_category(category, target, is_email=is_email)+ except ValueError as e:+ return [types.TextContent(type="text", text=json.dumps({"error": str(e)}))]+ else:+ results = await engine.check_all(target, is_email=is_email)++ # 2. Cross-Scan if requested+ if cross_scan:+ logger.info(f"Running cross-scan (depth={cross_depth}, sweep={cross_sweep})")+ cross_configs = CrossScanConfig(+ links=cross_links,+ emails=cross_emails,+ sweep=cross_sweep,+ depth=cross_depth,+ modules=(module_name,) if module_name else (),+ categories=(category,) if category else (),+ )+ # run_cross_scan modifies/returns a list of new results+ cross_results = await asyncio.to_thread(run_cross_scan, results, config, cross_configs)+ results.extend(cross_results)++ # 3. Filter and Format+ # Filter out empty results to save LLM context window limits+ found = [r for r in results if r.is_found()]+ logger.info(f"Found {len(found)} total valid results.")+ return [types.TextContent(type="text", text=into_json(found))]++async def handle_list_available_modules(arguments: dict) -> list[types.TextContent]:+ is_email = arguments.get("is_email", False)+ categories = load_categories(is_email=is_email)++ output: dict[str, Any] = {"scan_type": "email" if is_email else "username", "categories": {}}++ for cat_name, cat_path in categories.items():+ modules = load_modules(cat_path)+ site_names = [get_site_name(m) for m in modules]+ output["categories"][cat_name] = site_names++ return [types.TextContent(type="text", text=json.dumps(output, indent=2))]++async def call_tool(name: str, arguments: dict | None) -> list[types.TextContent]:+ """Route the tool call to the correct handler."""+ if not arguments:+ arguments = {}++ if name == "scan_username":+ return await execute_scan(arguments, is_email=False)+ elif name == "scan_email":+ return await execute_scan(arguments, is_email=True)+ elif name == "list_available_modules":+ return await handle_list_available_modules(arguments)+ else:+ logger.error(f"Unknown tool called: {name}")+ raise ValueError(f"Unknown tool: {name}")diff --git a/user_scanner/mcp/schemas.py b/user_scanner/mcp/schemas.pynew file mode 100644index 0000000..8c4fe48--- /dev/null+++ b/user_scanner/mcp/schemas.py@@ -0,0 +1,107 @@+import mcp.types as types+from typing import Any++def get_tool_list() -> list[types.Tool]:+ """Provide the list of tools available from this server."""++ # Common cross-scan parameters schema+ cross_scan_props = {+ "cross_scan": {+ "type": "boolean",+ "description": "Set to true to enable recursive OSINT pivoting. The engine will automatically extract emails, alternative usernames, and links found in the initial results and scan them too, building a deep web of connections."+ },+ "cross_links": {+ "type": "string",+ "enum": ["all", "verified", "none"],+ "description": "Controls link pivoting strictness during a cross-scan. 'all' pivots from any bio link. 'verified' only pivots from platform-proven connections. 'none' disables link pivoting. Default: 'all'."+ },+ "cross_emails": {+ "type": "string",+ "enum": ["all", "verified", "none"],+ "description": "Controls email pivoting strictness during a cross-scan. 'verified' (default) only scans addresses explicitly published in an email field. 'all' includes scraping emails from bio text."+ },+ "cross_depth": {+ "type": "integer",+ "description": "How deep the recursive link-following should go. Default: 1. Increase for deeper but slower investigations."+ },+ "cross_sweep": {+ "type": "integer",+ "description": "How many targets the cross-scan should automatically sweep against all modules. Default: 3. Set to 0 to only scan sites explicitly named in pivots (prevents handle collisions)."+ }+ }++ # Common basic parameters schema+ basic_props = {+ "category": {+ "type": "string",+ "description": "Optional category to restrict the scan to (e.g. 'social', 'gaming', 'dev'). Use list_available_modules to see options. Cannot be used with 'module'."+ },+ "module": {+ "type": "string",+ "description": "Optional specific site/module to restrict the scan to (e.g. 'github'). Use list_available_modules to see options. Cannot be used with 'category'."+ },+ "allow_loud": {+ "type": "boolean",+ "description": "WARNING: Set to true ONLY if stealth is not required. Enabling this runs aggressive modules that may trigger password reset emails and alert the target. Default: false (stealth mode)."+ },+ "no_nsfw": {+ "type": "boolean",+ "description": "Set to true to disable scanning of adult/NSFW sites. Default: false."+ },+ "proxies": {+ "type": "array",+ "items": {"type": "string"},+ "description": "An optional list of proxy URLs (e.g. 'http://proxy:port') to use for the scan. Recommended to avoid rate limits."+ },+ "timeout": {+ "type": "integer",+ "description": "Override default request timeout in seconds. Useful if the target sites are slow or you are using slow proxies."+ },+ "concurrency": {+ "type": "integer",+ "description": "Override default concurrency limit (how many requests to make in parallel)."+ }+ }++ username_props: dict[str, Any] = {"username": {"type": "string", "description": "The handle/username to scan for."}}+ username_props.update(basic_props)+ username_props.update(cross_scan_props)++ email_props: dict[str, Any] = {"email": {"type": "string", "description": "The email address to scan for."}}+ email_props.update(basic_props)+ email_props.update(cross_scan_props)++ return [+ types.Tool( # type: ignore+ name="scan_username",+ description="Scans for the presence of a username across platforms. Can be scoped to a specific category or module, and can recursively cross-scan linked profiles.",+ inputSchema={+ "type": "object",+ "properties": username_props,+ "required": ["username"]+ }+ ),+ types.Tool( # type: ignore+ name="scan_email",+ description="Scans for the presence of an email across platforms. Can be scoped to a specific category or module, and can recursively cross-scan linked profiles.",+ inputSchema={+ "type": "object",+ "properties": email_props,+ "required": ["email"]+ }+ ),+ types.Tool( # type: ignore+ name="list_available_modules",+ description="Lists all available categories and modules (sites) supported by the scanner. Use this to discover valid inputs for the 'category' and 'module' parameters.",+ inputSchema={+ "type": "object",+ "properties": {+ "is_email": {+ "type": "boolean",+ "description": "If true, lists email scan modules. If false, lists username scan modules. Default: False"+ }+ },+ "required": ["is_email"]+ }+ )+ ]diff --git a/user_scanner/mcp/server.py b/user_scanner/mcp/server.pynew file mode 100644index 0000000..32b7e20--- /dev/null+++ b/user_scanner/mcp/server.py@@ -0,0 +1,61 @@+import asyncio+import sys+import argparse+import logging++try:+ from mcp.server import Server+ from mcp.server.stdio import stdio_server+except ImportError:+ print("Error: The 'mcp' dependency is not installed.", file=sys.stderr)+ print("Please install it using: pip install user-scanner[mcp]", file=sys.stderr)+ sys.exit(1)++from user_scanner.mcp.schemas import get_tool_list+from user_scanner.mcp.handlers import call_tool++# Configure logging to write to stderr so it doesn't corrupt the JSON-RPC stdout stream+logging.basicConfig(+ level=logging.INFO,+ format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",+ stream=sys.stderr+)+logger = logging.getLogger("user-scanner-mcp")++app = Server("user-scanner")+[email protected]_tools() # type: ignore+async def handle_list_tools():+ """Provide the list of tools available from this server."""+ return get_tool_list()+[email protected]_tool() # type: ignore+async def handle_call_tool(name: str, arguments: dict | None):+ """Execute the requested tool and return the OSINT scan results."""+ return await call_tool(name, arguments)++async def run():+ """Run the server over standard input/output streams."""+ async with stdio_server() as (read_stream, write_stream):+ await app.run(+ read_stream,+ write_stream,+ app.create_initialization_options()+ )++def main():+ """Entry point for the MCP server script."""+ parser = argparse.ArgumentParser(description="user-scanner MCP server")+ parser.add_argument("-v", "--verbose", action="store_true", help="Enable verbose logging output to stderr")+ args = parser.parse_args()++ if not args.verbose:+ logger.setLevel(logging.CRITICAL)+ else:+ logger.setLevel(logging.INFO)+ logger.info("Starting user-scanner MCP server over stdio in verbose mode...")++ asyncio.run(run())++if __name__ == "__main__":+ main()