alphaXiv CLI

Official alphaXiv MCP documentation: Documentation

A pure CLI client for alphaXiv's official MCP tools.

This project uses the official MCP Python SDK to connect to the alphaXiv MCP server over OAuth 2.0, but keeps the user experience terminal-first:

• no browser auto-open
• no local callback server
• manual copy/paste login flow

What This CLI Does

The CLI exposes the official alphaXiv MCP tools as direct subcommands:

• answer_pdf_queries
• get_paper_content
• read_files_from_github_repository
• embedding_similarity_search
• full_text_papers_search
• agentic_paper_retrieval

It also provides:

• login
• logout

Install

uv sync

Quick Start

Show the available commands:

uv run alphaxiv --help

Log in:

uv run alphaxiv login

Run a tool:

uv run alphaxiv full_text_papers_search "Mixture of Experts"

Log out:

uv run alphaxiv logout

Login Flow

The login flow is fully manual.

When you run:

uv run alphaxiv login

the CLI will:

1. print an authorization URL
2. wait for you to open it in your browser
3. ask you to paste the full callback URL after login completes
4. exchange the authorization code for tokens and cache them locally

Example:

Open this URL in your browser to log in:

https://clerk.alphaxiv.org/oauth/authorize?...

After the browser redirects, copy the full callback URL from the address bar and paste it below.

Paste the full callback URL: http://127.0.0.1:8765/callback?code=...&state=...

If the browser does not successfully load the callback page, that is fine. You only need the full URL from the address bar.

Commands

login

Authenticate with alphaXiv and cache OAuth credentials locally.

uv run alphaxiv login

logout

Remove the cached OAuth state.

uv run alphaxiv logout

embedding_similarity_search

Search for papers by semantic or conceptual similarity.

uv run alphaxiv embedding_similarity_search \
  "Research on transformer architectures using self-attention mechanisms for sequence modeling."

full_text_papers_search

Search the alphaXiv database by keyword.

uv run alphaxiv full_text_papers_search "LoRA low-rank adaptation"

agentic_paper_retrieval

Run alphaXiv's agentic retrieval tool.

uv run alphaxiv agentic_paper_retrieval \
  "What are the latest approaches to reducing hallucination in large language models?"

get_paper_content

Fetch the content of a paper as text.

uv run alphaxiv get_paper_content https://arxiv.org/abs/1706.03762

Return the raw extracted text instead of the structured report:

uv run alphaxiv get_paper_content --full-text https://arxiv.org/abs/1706.03762

answer_pdf_queries

Ask questions about one or more papers or PDFs.

Repeat --url to pass multiple URLs. Repeat --query to pass multiple queries.

Single paper:

uv run alphaxiv answer_pdf_queries \
  --url https://arxiv.org/pdf/1706.03762 \
  --query "How does the attention mechanism work?"

Compare multiple papers:

uv run alphaxiv answer_pdf_queries \
  --url https://arxiv.org/pdf/1706.03762 \
  --url https://arxiv.org/pdf/1810.04805 \
  --query "Compare the architectures"

Ask multiple questions:

uv run alphaxiv answer_pdf_queries \
  --url https://arxiv.org/pdf/1706.03762 \
  --query "What is the main contribution?" \
  --query "What datasets were used?"

read_files_from_github_repository

Read files or directories from a paper's GitHub repository.

Read the repository overview:

uv run alphaxiv read_files_from_github_repository \
  --github-url https://github.com/openai/gpt-2 \
  --path /

Read a specific file:

uv run alphaxiv read_files_from_github_repository \
  --github-url https://github.com/openai/gpt-2 \
  --path src/model.py

Help Behavior

alphaxiv --help is the command directory. There is no separate list-tools command.

Help output behaves like this:

• before login: help uses built-in static descriptions
• after login: help attempts to load live tool descriptions from list_tools() and uses them when available
• if live metadata loading fails: help silently falls back to the built-in descriptions

This keeps --help available even when you are logged out, while still letting the CLI reflect the current server-side tool metadata once you have a cached login.

Token Storage

Tokens and dynamic client registration info are stored at:

.local/alphaxiv-oauth.json

You can override that path with:

uv run alphaxiv login --token-path /path/to/token.json

Verified Endpoints

• MCP endpoint: https://api.alphaxiv.org/mcp/v1
• Protected resource metadata: https://api.alphaxiv.org/.well-known/oauth-protected-resource
• Authorization server: https://clerk.alphaxiv.org
• Authorization server metadata: https://clerk.alphaxiv.org/.well-known/oauth-authorization-server

Notes

• The CLI uses OAuth authorization code flow with PKCE.
• The CLI does not auto-open a browser.
• The CLI does not start a local callback server.
• Tool invocation output is printed as JSON.