pwc CLI, Skill, and MCP server

A fast command-line client for exploring and editing the Papers with Code catalog, alongside a Skill for coding agents and a hosted Model Context Protocol server.

MCP server

The mcp_server package exposes an anonymous, read-only, agent-native interface over Streamable HTTP. It supports MCP 2026-07-28 and legacy 2025-era clients from one endpoint, with one tool per pwc research command: papers, related work, lineage, tasks, methods, conferences, organizations, frameworks, benchmarks, and filtered leaderboard evaluations.

Run it locally with:

uv run --project mcp_server pwc-mcp

See mcp_server/README.md for tools, resources, configuration, security limits, and hosting details.

Let your coding agent use pwc to:

• search papers
• browse benchmarks and find state-of-the-art (SOTA) by domain
• read paper metadata and Markdown
• discover recent, trending, and related work
• inspect paper lineage (follow-up work and predecessors)
• explore tasks, methods, conferences, organizations, and frameworks.

Public reads are anonymous: no account, API token, or Python environment is required.

pwc search "small vision language models" --limit 3
pwc paper info 2501.01234

It's recommended to also install the Skill so your coding agent knows how to use the CLI.

Installation

Prebuilt binary (recommended)

The installer downloads the binary for your platform, verifies its SHA-256 checksum, and installs it as ~/.local/bin/pwc:

pwc_repo=https://raw.githubusercontent.com/huggingface/pwc-cli/main
curl -LsSf "$pwc_repo/standalone_cli/install.py" | python3

The installer selects the latest release by default. Pass --version VERSION after python3 - to explicitly pin a release. It also reports whether ~/.local/bin is on PATH and prints a persistent shell instruction when needed.

Prebuilt releases support:

• Linux x86-64
• macOS Intel (x86-64)
• macOS Apple Silicon (arm64)

Every release includes checksum files and GitHub build-provenance attestations. See the latest release to download and verify an artifact manually.

Install from source

Python 3.10 or newer is required for source installations.

With uv:

uv tool install 'git+https://github.com/huggingface/pwc-cli.git#subdirectory=standalone_cli'

Or with pipx:

pipx install 'git+https://github.com/huggingface/pwc-cli.git#subdirectory=standalone_cli'

To work from a clone instead:

git clone https://github.com/huggingface/pwc-cli.git
cd pwc-cli
uv tool install ./standalone_cli

Confirm the installation:

pwc version

Add the CLI Skill

Skills give coding agents the context they need to choose and use pwc commands effectively. The Skill is generated by your locally installed CLI, so it matches that CLI version.

# Install for this project. Works with Codex, Cursor, OpenCode, and other
# agents that load Skills from .agents/skills.
pwc skills add

# Install for all projects in ~/.agents/skills.
pwc skills add --global

# Also make the Skill available to Claude Code.
pwc skills add --claude
pwc skills add --claude --global

For another coding-agent harness, pass its Skills directory explicitly:

pwc skills add --dest /path/to/skills

An existing installation is left untouched. Use --force to replace it with the Skill generated by the currently installed CLI.

Quick start

Search the paper catalog:

pwc search "retrieval augmented generation"
pwc search "vision transformers" --mode semantic --limit 20
pwc search "attention" --page 2 --limit 10
pwc search "attention" --has-official-implementation

Inspect or read a paper:

pwc paper info 1706.03762  # includes tagged organizations
pwc paper info 1706.03762 --include-resources  # linked GitHub, project, and HF URLs
pwc paper info 1706.03762 --include-evals      # evaluation Markdown table
pwc paper info "Attention Is All You Need"
pwc paper read 1706.03762

Discover papers:

pwc paper recent --limit 10
pwc paper recent --implementation-coverage
pwc paper trending --limit 20 --max-age-days 90
pwc paper related 1706.03762 --limit 4
pwc paper lineage list 1706.03762

List and filter papers:

pwc paper list --conference NeurIPS --page-size 20
pwc paper list --organization Qwen --order-by date_published
pwc paper list --author "Kaiming He" --search drift --order-by date_published
pwc paper list --task "Image Classification" --method Transformer
pwc paper list --conference "CVPR 2026" --framework PyTorch
pwc paper list --search "diffusion" --start-date 2025-01-01 --end-date 2025-01-31
pwc paper list --order-by citation_count --order-dir desc
pwc paper list --has-official-implementation --implementation-coverage

Explore the research taxonomy and conferences:

pwc task list
pwc task list --area Vision
pwc task list --group-by-area  # force grouped Markdown when piping/capturing
pwc task --name "scene-text-recognition"
pwc method --name Transformer
pwc method list --area Audio
pwc method list --area General --introduced-year 2017
pwc conference --name "CVPR 2025"
pwc conference list
pwc conference list --year 2025
pwc organization --name NVIDIA
pwc organization list --featured-only
pwc framework --name vLLM
pwc framework list --platform gpu

Browse benchmarks:

pwc benchmark list
pwc benchmark list --group-by-area --area Vision
pwc benchmark list --search ImageNet
pwc benchmark list --task OCR
pwc benchmark list --task image-classification --include-descendants
pwc benchmark list --min-eval-count 10 --order-by paper_count --order-dir desc
pwc benchmark --name "SWE-Bench Pro"
pwc benchmark --name wikitext-103 --is-open true --max-parameters 3B

Command reference

Every PAPER argument accepts a modern or legacy arXiv ID, a numeric external-paper ID, or a quoted exact paper title. Title matching is case-insensitive. Ambiguous titles are rejected with the matching IDs instead of silently selecting one paper.

Command	Description
pwc search QUERY	Search for papers by title, topic, author, or arXiv ID
pwc paper info PAPER	Show paper metadata, abstract, predecessors, and successors; optionally include resources or an evaluation Markdown table
pwc paper read PAPER	Print the stored paper Markdown
pwc paper list	List and filter papers
pwc paper recent	List recently published papers
pwc paper trending	List trending papers
pwc paper related PAPER	Find related papers
pwc paper lineage list PAPER	Show linked Markdown sections for a paper's predecessors and successors
pwc task list	Group tasks by area with paper, benchmark, and evaluation counts; support flat pagination and area filters
pwc task --name NAME	Show task-page details, including frameworks, sister tasks, common methods, benchmarks, and papers
pwc method --name NAME	Show details for an exact method name, full name, slug, or ID
pwc method list	List methods and filter them by research area or introduction year
pwc conference --name NAME	Show details for an exact conference name, slug, or ID
pwc conference list	List conferences and filter them by year
pwc organization --name NAME	Show details for an exact organization name, slug, or ID
pwc organization list	List organizations, optionally restricting to featured organizations
pwc framework --name NAME	Show details for an exact framework name, slug, or ID
pwc framework list	List frameworks by domain, category, or platform
pwc benchmark list	Group top benchmarks by area and task; support flat filters and task-trend ranking
pwc benchmark --name NAME	Show a benchmark's top models, parameter counts, papers, scores, and publication dates; optionally apply an inclusive model-size limit
pwc skills add	Install the version-matched Skill for coding agents
pwc version	Show the CLI and API contract versions

Run pwc --help, pwc COMMAND --help, or pwc paper COMMAND --help for all available options.

Output and scripting

Task and benchmark lists use grouped Markdown in an interactive terminal; --flat forces their paginated tables and --group-by-area forces Markdown when piping. Flat benchmark lists use aligned columns in both terminals and captured output; use --json for machine-readable benchmark rows. Other list and search commands use aligned columns in a terminal and lossless TSV when captured. Benchmark details use an aligned table in a terminal and Markdown when piped or captured. Other detail commands use labeled metadata or Markdown. Paper discovery commands accept --implementation-coverage to add official-code status and the total linked repository count; JSON and pwc paper info always include them. A false official-code status only means the catalog has no linked official repository. Search and paper-list filters using --has-official-implementation fail closed unless the API confirms the filter. Add --json to any data command for machine-readable output:

pwc search "language models" --limit 5 --json
pwc paper info 1706.03762 --include-evals --json
pwc benchmark list --task image-classification --json

JSON responses include a top-level schema_version and data field:

{
  "schema_version": "v1",
  "data": {}
}

The stable exit codes are:

Code	Meaning
0	Success
2	Invalid command or arguments
3	Network or server failure
4	Invalid API response

Configuration

pwc uses https://paperswithcode.co/api/v1 by default. To connect to another compatible v1 API, set PWC_API_URL:

PWC_API_URL=http://localhost:8000/api/v1 pwc search "transformers"

Scope

Public catalog commands are anonymous and read-only. Paper editing is an explicit authenticated workflow scoped to one confirmed paper; the CLI does not include general ingestion, image, embedding, CRON, or infrastructure maintenance commands.

Development

Run the CLI from a checkout:

uv run --project standalone_cli pwc --help

Run the focused test and contract checks:

uv run --project standalone_cli --with pytest pytest standalone_cli/tests
uv run python standalone_cli/scripts/check_contract.py

The implementation lives in standalone_cli.

Edit a paper with your agent

Requires a server with the paper-edit API enabled. Sign in using the browser link and confirm the paper and code. This grants one hour of write access to that paper; each batch publishes immediately under your HF username.

pwc auth login --paper 123       # --no-browser for remote machines
pwc paper edit export 123 --output edits.json
# Add explicit operations to edits.json; current is reference material.
pwc paper edit preview 123 --file edits.json
pwc paper edit submit 123 --file edits.json
pwc auth status --paper 123
pwc auth logout --paper 123

For example, add the following to the exported operations array, substituting real existing task/dataset/metric identifiers. A metrics dictionary lets you submit multiple scores without repeating model and benchmark details:

{
  "section": "evaluations",
  "payload": {
    "task_id": 1,
    "dataset_id": 2,
    "model_name": "Example model",
    "methodology": "Test split, zero-shot; Table 3",
    "metrics": {"Accuracy": 90.5, "F1": 88.1},
    "source_url": "https://arxiv.org/abs/2601.00001"
  }
}

Add evaluation_id alongside section to correct a row. Other supported sections are tasks, methods, repositories, project_pages, hf_artifacts, and source_url. Section replacements must retain unrelated entries. Evaluation updates preserve omitted fields. Existing benchmark/metric definitions are required; evaluation deletion and rank overrides are excluded.

Batches contain at most 50 operations and 1 MiB. Invalid or stale batches write nothing. Retry uncertain network results with the exact same document and idempotency key. For a stale revision, export again and reconcile before retrying. Accounts share a 20-distinct-paper daily limit (UTC) and 30-publication-per-minute limit across the website and CLI; admins are exempt. pwc skills add --force installs the detailed agent workflow.

Credentials are stored in mode-0600 files inside the mode-0700 directory ~/.config/pwc/edit-credentials, keyed by API base URL and paper. Never copy these files into prompts or repositories. PWC_API_URL selects the target API; editing requires HTTPS, except on loopback development servers, and refuses redirects. Public read commands never load edit credentials.