Skip to content

🕵️‍♂️ (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.

feat: add Model Context Protocol (MCP) server support

Kaifb61ce4dd155c
diff --git a/.github/workflows/lint-pr.yml b/.github/workflows/lint-pr.yml
index 464a563..614eb1f 100644
--- a/.github/workflows/lint-pr.yml
+++ b/.github/workflows/lint-pr.yml
@@ -25,7 +25,7 @@ jobs:
- name: Install linters
run: |
python -m pip install --upgrade pip
- pip install httpx curl_cffi colorama types-colorama rich
+ pip install httpx curl_cffi colorama types-colorama rich mcp
pip install ruff==0.15.22 mypy
- name: Run ruff
diff --git a/.github/workflows/lint-push.yml b/.github/workflows/lint-push.yml
index 9b8d5e7..bbae2b7 100644
--- a/.github/workflows/lint-push.yml
+++ b/.github/workflows/lint-push.yml
@@ -26,7 +26,7 @@ jobs:
- name: Install linters
run: |
python -m pip install --upgrade pip
- pip install httpx curl_cffi colorama types-colorama rich
+ pip install httpx curl_cffi colorama types-colorama rich mcp
pip install ruff==0.15.22 mypy
- name: Run ruff
diff --git a/pyproject.toml b/pyproject.toml
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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()