styx-search

Search 500,000+ open-access papers, standards, textbooks, and legal documents — right from your terminal or your AI agent.

styx-search is a zero-configuration CLI and Model Context Protocol (MCP) server for the Styx Open Knowledge Archive. Every source in the archive is open access or public domain — no paywalls, no accounts required to search.

• For humans — search, export citations in 11 formats (BibTeX, APA, MLA, Chicago, IEEE, Harvard, RIS, Bluebook, OSCOLA, ISO 690, ANSI Z39), and download PDFs to disk with one command.

• For AI agents — a stdio MCP server with five tools, so Claude, Cursor, Windsurf, OpenCode, or any MCP client can search, resolve identifiers (RFC, DOI, arXiv, PMID, PMCID, NIST/FIPS, W3C, US case citation), and save PDFs into your workspace.

• 100% self-contained — talks only to the public HTTPS API. No API keys, no sign-up, no internal infrastructure.

Install

pip install styx-search

Or from source:

git clone https://github.com/0x923041-dotcom/styx-cli.git
cd styx-cli
pip install .

Requires Python 3.8+.

Related MCP server: Crossref Academic MCP Server

Quick start

# Search — supports source:/lang:/category: directives
styx search "attention is all you need" --limit 5
styx search "source:nist zero trust" --category "Computer Science & Tech"
styx search "source:eurlex AI act" --json
styx search "meditations marcus aurelius" --markdown   # for Obsidian/Notion
styx search "diffusion models" --offset 20            # paginate past the first page

# Resolve a known identifier straight to its document(s)
styx resolve "RFC 2119"
styx resolve "doi:10.1145/3290605.3300333"
styx resolve "2604.08499"                              # arXiv
styx resolve "PMID 41961061"                           # PubMed
styx resolve "PMC10601397"                             # PubMed Central
styx resolve "NIST FIPS 199"
styx resolve "410 U.S. 113"                            # US case citation (Supreme Court)
styx resolve "20-5364"                                 # federal docket
styx resolve "RFC 2119" --json

# Download the original PDF
styx download 297465 -o paper.pdf          # by document ID
styx download "https://arxiv.org/pdf/2604.21816v1.pdf"   # by URL

# Citations — 11 formats: bibtex, apa, mla, chicago, ieee, harvard,
# ris, bluebook, oscola, iso690, ansiz39
styx cite 7288 --format bibtex
styx cite 7288 --format apa
styx cite 7288 --format iso690

# Document metadata
styx info 2844

# License key (Pro) + quota
styx auth STYX-XXXX-XXXX-XXXX
styx quota

# Version
styx --version

# AI agent server
styx mcp

Example

$ styx search "source:nist zero trust" --limit 3

Styx - 3 results for "source:nist zero trust"
  #  Year  Title                                       Author                  Source           PDF
  1  n.d.  NIST SP 1800-35: Implementing a Zero Trust  Scott Rose (NIST); …    NIST             [x]
  2  n.d.  NIST SP 800-207: Zero Trust Architecture     Scott Rose (NIST); …    NIST             [x]
  3  n.d.  NIST SP 800-207A: A Zero Trust Architecture Ramaswamy Chandramo…   NIST             [x]

  Tip: styx download 2844 saves the PDF, styx cite 2844 exports a citation.

Query words are highlighted in gold in the title column. The PDF column shows [x] when a direct PDF link is available; [ ] rows still surface the source URL via styx info <id>.

Search directives

The CLI understands the same directives as the Styx web app — they are stripped from the query and applied as real filters:

Directives can be combined freely: styx search "cat:\"Computer Science & Tech\" source:nist lattice cryptography".

Resolve

styx resolve recognises several identifier shapes and returns a typed response (kind: rfc | doi | arxiv | pmid | pmcid | nist | w3c | case plus fallback null for plain text). Unrecognised identifiers degrade to a regular search so the command never fails silently.

Model Context Protocol (MCP)

The styx mcp command starts a stdio JSON-RPC MCP server. It is dependency-free (no MCP SDK required) and works with any MCP client.

Tools

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "styx": {
      "command": "styx",
      "args": ["mcp"]
    }
  }
}

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

{
  "mcpServers": {
    "styx": {
      "command": "styx",
      "args": ["mcp"]
    }
  }
}

OpenCode / Windsurf / Antigravity

The same JSON shape works in any MCP-aware client — point it at styx mcp and the five tools above are exposed automatically.

After adding, restart the client and you can ask, for example:

"Find the NIST post-quantum encryption standard and download the PDF into my workspace."

Manual smoke test

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | styx mcp

Fair use

Every source in Styx is open access or public domain, and searching is free. To keep the archive open for everyone, a trial allowance applies per client (and then a rate limit). When a limit is reached, the CLI returns a clear, non-blocking message:

Free trial allowance exhausted. Add a license key to continue at higher
limits: docs at https://styx-iota.vercel.app or `styx auth <key>`.

Add a license key once with styx auth <key> — it is stored in ~/.styx/config.json and sent with every request. No account or sign-up is required to search. styx quota reports your current tier (public / pro / institutional).

Configuration

State lives in ~/.styx/config.json:

{
  "api_base": "https://styx-iota.vercel.app",
  "license_key": "",
  "default_limit": 10,
  "default_citation_format": "bibtex"
}

Override the API base (for staging, self-hosted mirrors, or a local proxy) by editing api_base. Set default_limit to change the search page size; set default_citation_format to any of the 11 supported format names.

Development

pip install -e ".[test]"     # or: pip install -e . && pip install pytest
pytest tests/                # 41 offline tests (mocked HTTP, no network)

The test suite is fully offline — httpx is patched with a MockTransport and StyxClient is stubbed where it composes other services. No test makes a real network call.

License

MIT — see LICENSE.

Built on the Styx Open Knowledge Archive — 500+ living sources: arXiv, NIST, OWASP, CISA, PubMed/PMC, MIT OpenCourseWare, EUR-Lex, Project Gutenberg, and more.