# pwc CLI, Skill, and MCP server
A fast command-line client for exploring and editing the
[Papers with Code](https://paperswithcode.co) catalog, alongside a Skill for
coding agents and a hosted Model Context Protocol server.
## MCP server
The [`mcp_server`](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.
A hosted instance runs at `https://paperswithcode.co/mcp`. It needs no API key
or sign-in. Connect your client:
```bash
# Claude Code
claude mcp add --transport http paperswithcode https://paperswithcode.co/mcp
# Codex
codex mcp add paperswithcode --url https://paperswithcode.co/mcp
```
For Cursor (`.cursor/mcp.json`) and other clients that read an `mcpServers`
config:
```json
{
"mcpServers": {
"paperswithcode": {
"url": "https://paperswithcode.co/mcp"
}
}
}
```
In VS Code (`.vscode/mcp.json`), use `"servers"` with `"type": "http"` and the
same URL. In Claude.ai or Claude Desktop, add it under Settings → Connectors →
Add custom connector.
Run it locally with:
```bash
uv run --project mcp_server pwc-mcp
```
See [`mcp_server/README.md`](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.
```bash
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`:
```bash
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](https://github.com/huggingface/pwc-cli/releases/latest)
to download and verify an artifact manually.
### Install from source
Python 3.10 or newer is required for source installations.
With [`uv`](https://docs.astral.sh/uv/):
```bash
uv tool install 'git+https://github.com/huggingface/pwc-cli.git#subdirectory=standalone_cli'
```
Or with [`pipx`](https://pipx.pypa.io/):
```bash
pipx install 'git+https://github.com/huggingface/pwc-cli.git#subdirectory=standalone_cli'
```
To work from a clone instead:
```bash
git clone https://github.com/huggingface/pwc-cli.git
cd pwc-cli
uv tool install ./standalone_cli
```
Confirm the installation:
```bash
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.
```bash
# 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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```json
{
"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`:
```bash
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:
```bash
uv run --project standalone_cli pwc --help
```
Run the focused test and contract checks:
```bash
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`](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.
```bash
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:
```json
{
"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,
x_threads, and source_url. `x_threads` takes `{"x_threads": [post URLs]}` in
display order (at most 10); link only posts in which the paper's authors or
their organization introduce the paper. 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.