Library, MCP server and TUI

Besides the command line, Aliens Eye can be driven from Python, by an LLM agent over MCP, or from an interactive terminal UI.

#Python library

aliens_eye.api is the stable surface for building on Aliens Eye. It returns plain dicts shaped like the JSON report and prints nothing by default. Everything outside aliens_eye.api is internal and may change between minor releases.

import asyncio
from aliens_eye import api

async def main():
    sites = api.load_sites(exclude_nsfw=True)
    report = await api.scan(
        "someone",
        sites=sites,
        on_result=lambda user, r: print(r["site"], r["status"]),  # optional progress hook
    )
    correlation = await api.correlate(report)
    print(len(correlation["clusters"]), "clusters")

asyncio.run(main())

#load_sites(exclude_nsfw=False, path=None, *, catalog=None, tags=None, sources=None)

The catalog as a mapping of {site_name: url_template}. Load it once to know the total up front, for a progress bar, or to filter it before scanning:

sites = api.load_sites(catalog="extended", tags=["coding"], exclude_nsfw=True)
report = await api.scan("someone", sites=sites)

The mapping carries each site's rules alongside the URL. Pass it to scan unchanged: converting it with dict(), or keeping only the URLs, drops the rules. Replacing a URL in the mapping drops that entry's stale rules.

#await scan(username, level="basic", *, sites=None, use_ml=True, proxy=None, on_result=None, quiet=True, catalog=None)

Scans one username and returns the report. level is basic, intermediate or advanced; sites defaults to the full extended catalog; on_result(username, result) is called as each site finishes. Raises ValueError for a username shorter than two characters or an unknown level.

#await correlate(report)

Clusters the Found and Maybe profiles of a report that look like the same person; see Investigations.

#match_profile_url(url, sites=None) and profile_url(site, username, sites=None)

Read a profile link back into a site and username, and the other way round:

api.match_profile_url("https://www.instagram.com/_someone_/")
# [ProfileMatch(site='instagram', username='_someone_')]

api.profile_url("github", "someone")
# 'https://github.com/someone'

match_profile_url returns [] for a URL that is not a profile on a known site, such as a repository or a navigation page.

#await fetch_page(url, *, proxy=None, timeout=20.0, max_bytes=1_000_000, allow_private=False)

Fetches one page whose address came from somewhere you do not control, such as a link in a bio. Only http(s) is fetched, and only from public addresses: the URL and every redirect are checked and the connection is pinned to a public address, so a link cannot steer the request at a service on your network. allow_private=True lifts that for a network you own; through a proxy, the proxy resolves names and the pinning does not apply.

It never raises for a bad or unreachable URL. It returns {"url", "final_url", "status", "html", "error"}, with error saying why, for example "host resolves to a non-public address".

#MCP server

pip install "aliens-eye[serve]"
aliens_eye serve

Runs a Model Context Protocol server over stdio, so an LLM agent can use Aliens Eye as a tool. It offers three tools:

To add it to an MCP client, give the command and its argument; for example, in a client that reads an mcpServers configuration:

{
  "mcpServers": {
    "aliens-eye": { "command": "aliens_eye", "args": ["serve"] }
  }
}

aliens_eye serve --sites my-sites.json scans a custom site list instead of the catalog, and --no-ml turns the model off. An agent asking for scans makes real requests to thousands of sites, so keep a person in the loop for what it scans.

#Terminal UI

pip install "aliens-eye[tui]"
aliens_eye tui
aliens_eye tui someone -l intermediate

Scans a username, then opens every result in a filterable, searchable table in the terminal. Without a username on the command line, it asks for one.

It takes -l/--level, --sites and --no-ml like a normal scan.