papers-skill MCP server
Commit Nov 9, 2026Enables an AI agent to search scientific literature, generate paper digests, and manage research notes without consuming main conversation context.
Also known as rokokol/papers-skill
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is papers-skill MCP?
papers-skill enables an AI agent to search scientific literature, generate paper digests, and manage research notes without consuming main conversation context.
Summary generated from the project's README
About papers-skill MCP server
Researchers and developers can manage scientific literature without cluttering their main conversation context by using this tool. It allows an AI agent to search databases like arXiv, PubMed, and Semantic Scholar to find specific papers via DOI or arXiv ID. Instead of dumping entire PDFs into the chat, a subagent reads the document and returns a concise digest of a bounded length. This approach preserves the primary conversation window for high-level reasoning and comparison.
The setup is local and relies on the paper-search-mcp server. Users can manage installation through Nix or by adding the skill via npx. For those using Claude Code, it functions as a plugin. Security is prioritized by using an environment file for API keys, ensuring sensitive credentials like Semantic Scholar or CORE keys never enter the chat history. The system also supports filing research digests directly into an Obsidian vault using a custom profile to maintain consistent note-taking styles.
What you can do with it
- 1Summarize scientific papersAsk the agent to generate a brief digest of a specific paper using its DOI or arXiv ID.
- 2Compare multiple research articlesRequest a comparison between different paper digests to identify similarities or differences.
- 3Organize research in ObsidianFile a paper digest into a specific folder within your Obsidian vault using your preferred formatting.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
PAPER_SEARCH_MCP_CORE_API_KEYPAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEYPAPER_SEARCH_MCP_UNPAYWALL_EMAIL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerokokol/papers-skill is public and reachablegithub.com/rokokol/papers-skill ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/rokokol/papers-skill ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubpapers skill
Scientific papers for an agent, without spending the conversation on them (。•̀ᴗ-)✧
A paper is long and its PDF is worse: the text of one article is a large share of a conversation's context, and a literature question is several of them. This skill keeps the reading out of the main conversation. The agent finds and decides; a subagent with its own context reads one paper and returns a digest of bounded length; the agent compares digests and, only when you say so, files one into your notes
The sources come from paper-search-mcp, which reaches arXiv, PubMed, Semantic Scholar, OpenAlex, Crossref, bioRxiv and more through one MCP server or one CLI. This repository packages it for Nix, because the PyPI release breaks under the current MCP SDK and nixpkgs does not carry it, and ships a Home Manager module so the keys never enter a store path or a chat
Contents
- Install the skill
- Install the sources
- Register the server
- Keys
- A corpus with PaperQA2
- Notes in a vault
- Checks
- Layout
Install the skill
npx skills add -g rokokol/papers-skill # for you, everywhere
npx skills add rokokol/papers-skill # for the project you are standing in
Claude Code also takes it as a plugin:
/plugin marketplace add rokokol/skills
/plugin install papers@rokokol-skills
With the Home Manager module below, programs.papers.skill is the skill's directory at the flake's revision, for a module that hands skills to your agents. The skill then always matches the server the same flake builds
or by hand — clone into whichever skills directory your agent reads:
git clone https://github.com/rokokol/papers-skill ~/.claude/skills/papers
[!NOTE] A skill has no version to pin — it is read at whatever revision you have checked out, so
git pullis the whole upgrade path and the changelog is dated rather than numbered
Then ask for papers on a topic, a DOI or an arXiv id, a digest, or a comparison — in English or with the Russian triggers listed in SKILL.md. Nothing in SKILL.md is about installation; everything below is
Install the sources
The skill needs paper-search-mcp on the machine, as the MCP server, the paper-search CLI, or both; one package provides both binaries
With Nix, the flake builds the PyPI release against nixpkgs' MCP SDK 1.x, which is what keeps the server importable:
nix build github:rokokol/papers-skill#paper-search-mcp
nix profile install github:rokokol/papers-skill#paper-search-mcp
Or declaratively, as a Home Manager module. The consumer adds the flake as an input and enables the module; envFile is optional and points both binaries at a file with the keys, rendered by whatever secret store the consumer runs:
{
inputs.papers-skill = {
url = "github:rokokol/papers-skill";
inputs.nixpkgs.follows = "nixpkgs";
};
}
{ inputs, ... }:
{
imports = [ inputs.papers-skill.homeModules.default ];
programs.papers = {
enable = true;
envFile = "/run/secrets/rendered/paper-search.env";
};
}
An overlay is there too, inputs.papers-skill.overlays.default, for a consumer who reaches for pkgs.paper-search-mcp
Without Nix, install the release with the SDK pinned below 2, which upstream's own metadata does not do:
uv tool install --with "mcp<2" paper-search-mcp==0.1.4
[!WARNING] Upstream's
download_with_fallbacktool tries Sci-Hub after the open-access routes, and that is on by default. Whether that belongs on your machine is your call, and the skill says so wherever a PDF came from that route;use_scihub: falseon the call turns it off
Register the server
Claude Code starts a stdio MCP server per session and stops it on exit; nothing is hosted
With the Home Manager module, the server is already in Home Manager's shared MCP list as paper-search, with envFile passed to it. An agent reads that list once its integration is on:
{
programs.mcp.enable = true;
programs.claude-code.enableMcpIntegration = true;
}
By hand, with the binary on PATH:
claude mcp add --scope user --transport stdio paper-search -- paper-search-mcp
claude mcp list
The skill assumes the name paper-search, so its tools are mcp__paper-search__*. Another client, or a session where the server is not registered, falls back to the paper-search CLI, which the skill drives from Bash; the per-source read_*_paper tools and download_with_fallback exist only on the server
[!NOTE] When a download falls back to a PDF on disk, the reading subagent opens it with Claude Code's
Readtool, which renders PDFs throughpdftoppmfrom poppler; withoutpoppler-utilsonPATHthat rung fails and the subagent moves down the ladder in references/reader.md. Install poppler if you want the PDF rung to work
Keys
Every source works without a key. Free keys change how well: a Semantic Scholar key takes you off the anonymous pool shared by everyone, a CORE key stops its frequent 500s, and an email for Unpaywall turns on the open-access step of the download fallback, which is otherwise skipped. The server reads them from an env file: the path in PAPER_SEARCH_MCP_ENV_FILE, else ~/.config/paper-search-mcp/.env
PAPER_SEARCH_MCP_SEMANTIC_SCHOLAR_API_KEY=...
PAPER_SEARCH_MCP_CORE_API_KEY=...
PAPER_SEARCH_MCP_UNPAYWALL_EMAIL=you@example.com
Keep that file out of the repository and out of the chat: the skill never asks for a key and never puts one on a command line. references/sources.md lists the rest of the variables and what each source does without them
A corpus with PaperQA2
One paper is read by a subagent; a question across a whole folder of papers is retrieval, and PaperQA2 does it. It is not in nixpkgs and pins an older litellm, so the flake carries it as a locked environment, nix/paperqa/uv.lock resolved by uv and built by uv2nix from wheels, exposed as packages.paper-qa with the pqa command. The module's corpus block installs it and writes the settings preset for local models, so nothing leaves the machine:
programs.papers.corpus = {
enable = true;
directory = "/home/me/.cache/papers"; # the folder the skill downloads into
};
Then pqa -s papers index <folder> once, and pqa-evidence -s papers "<query>" for every question: it returns the passages PaperQA2 retrieved, untouched, and the agent reasons over them, since a local model retrieves well and reasons less well. pqa -s papers ask "…" has the local model answer instead, in about a minute of GPU time. Which models run by default and how to change them, the commands, and the settings that make ask work on Ollama at all are in references/paperqa.md
Notes in a vault
The note mode files a digest into an Obsidian vault, but only when you say so, and never in a shape invented here: your vault has its own style, and the skill defers to it. Tell it how through one profile in the vault:
# $OBSIDIAN_VAULT_PATH/.claude/papers/profile.yml
style_skill: conspect
preset: paper
notes_dir: "04. Книжная полка/Статьи"
attachments_dir: "00. Вложения/Статьи"
style_skill is a vault-local skill under .claude/skills/ that owns note style, preset the preset of that skill for a paper note, and the two folders are where notes and kept PDFs go. Without a profile the skill asks for a path and writes plain Markdown. references/profile.md has every field
The vault is found through OBSIDIAN_VAULT_PATH, the variable the official Obsidian CLI understands; set it in the env block of ~/.claude/settings.json so every session sees it
Checks
nix develop -c ./check.sh
nix flake check
check.sh is the gate CI runs: the scripts lint, the PMC reader passes its unit tests, the workflows are valid and pinned, the vendored checkers still match their lock, SKILL.md loads and every reference and link resolves, the changelog obeys its rules, every MCP tool and argument the documents name is one the packaged server advertises, and every source they route to is one its CLI lists. The vendored checkers and the document checks are each proven able to fail on a planted defect during the same run; the linters are trusted to fail. nix flake check builds the packages and asks each one for its help, offline
Layout
SKILL.md what the agent loads: modes, the reading subagent's contract, the never list
references/ sources by area, the reader prompt, the digest template, the profile, the corpus mode
nix/ package.nix for paper-search-mcp, paperqa/ with PaperQA2's lock, home-module.nix for Home Manager
flake.nix packages, the module, the overlay, the dev shell and the checks
tools/evidence.py pqa-evidence: PaperQA2's retrieval without its answer model
tools/pmc_text.py the reader's first rung for a biomedical paper: PMC's open-access text
tests/mcp-tools.py asks a stdio MCP server what tools it has and what arguments each takes
tests/test_*.py unit tests the gate runs, with no request leaving the machine
check.sh the gate, self-tested against planted defects
check-*.sh vendored checkers, kept byte-equal to their source by vendor-sync.sh
WORKAROUNDS.md what exists only because something upstream is broken, and how to tell when it can go
papers-skill MCP questions
How does the skill handle long scientific papers?
It uses a subagent with its own context to read a paper and return a bounded-length digest, keeping the full text out of the main conversation.
Can I integrate my research notes with Obsidian?
Yes, the note mode can file digests into an Obsidian vault using a custom profile to match your specific style and directory structure.