Installation

Research Scan is a Python package published on PyPI as research-scan. It needs Python 3.11 or newer and uv.

Install

uvx research-scan doctor          # run any command without installing
uv tool install research-scan     # or put it on PATH permanently

uvx resolves and caches the package on first use, then runs it. Nothing is added to your PATH, which makes it the right choice for trying the tool out and for the MCP configuration further on. uv tool install is the choice once you want research-scan available as a normal command.

Both routes install the same package. There are no optional extras to choose: the MCP server ships in the core dependencies.

Confirm the install

version reports more than a number — it reports what this particular install can do.

research-scan version

research-scan 0.5.1
python       3.13.13
platform     macOS-14.2.1-arm64-arm-64bit-Mach-O
mcp          enabled

The python and platform lines reflect the machine that ran the command; yours will differ. mcp enabled is the one to read: it means fastmcp imported cleanly and the MCP server will start. Because fastmcp is a core dependency rather than an extra, disabled means a broken or incomplete install, not a missing option — reinstall with uv tool install research-scan.

The same report is available as JSON:

research-scan version --json

{
  "version": "0.5.1",
  "python": "3.13.13",
  "platform": "macOS-14.2.1-arm64-arm-64bit-Mach-O",
  "mcp": "enabled"
}

The bare --version flag on the root command prints only the number, so scripts that already parse it keep working:

research-scan --version

0.5.1

There is no one-shot scan command

research-scan --help lists fourteen commands, and scan is not one of them:

$ research-scan scan --help
Usage: research-scan [OPTIONS] COMMAND [ARGS]...
Try 'research-scan --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────╮
│ No such command 'scan'. Did you mean 'schema'?                               │
╰──────────────────────────────────────────────────────────────────────────────╯

This is by design. The pipeline needs a model’s judgement between stages — screening scores, gap queries, the rerank — and a one-shot command would have to fabricate them. You drive Research Scan from an agent, which supplies that judgement at each decision point. See your first scan.

Shell completion

eval "$(research-scan completion bash)"   # add to ~/.bashrc
eval "$(research-scan completion zsh)"    # add to ~/.zshrc
research-scan completion fish > ~/.config/fish/completions/research-scan.fish

Next

Configure your credentials, then check that everything works.