mcpField
O
opencite

opencite

github.com/neuromechanistProductivity5038 installsUpdated today
Repository

About opencite

OpenCite is a CLI for academic literature search and citation management, aimed at researchers. It combines results from multiple scholarly sources with deduplication, and supports paper retrieval, PDF conversion, and batch workflows.

Key features

  1. 01Searches multiple literature sources
  2. 02Deduplicates search results
  3. 03Explores citation relationships
  4. 04Downloads and converts PDFs
  5. 05Batch-fetches papers

Use cases

  1. 01Finding foundational and recent papers
  2. 02Tracing papers that cite a study
  3. 03Downloading and converting a reading list
  4. 04Generating BibTeX references

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/neuromechanist/research-skills --skill opencite

After installing, type/opencitein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
api-keys-and-config.md
cli-reference.md
common-workflows.md

Details

From the project README

OpenCite CLI

OpenCite is a CLI tool for academic literature search and citation management. It aggregates results from Semantic Scholar, OpenAlex, PubMed, arXiv, and bioRxiv/medRxiv, deduplicates them, and outputs formatted results. It also supports PDF retrieval, PDF-to-markdown conversion, and batch operations.

Installation

# Recommended
uv pip install opencite

# Alternative: run without installing
uvx opencite --version

PDF conversion support (markitdown and markit-mistral) is included by default. When MISTRAL_API_KEY is set, markit-mistral handles math, tables, and complex layouts. Otherwise, markitdown (free, local) is the fallback.

For development:

uv sync --extra dev

Research Workflow

Follow this end-to-end workflow for literature research, paper retrieval, or reading material on a topic.

1. Search for relevant papers

Choose the search strategy based on the request:

  • Canonical/foundational papers: uvx opencite canonical "topic" --max 10
  • Recent or specific papers: uvx opencite search "query" --max 20 --sort citations
  • Citation graph exploration: uvx opencite cite "DOI" --direction both
  • Combine strategies when appropriate (e.g., canonical for background + search for recent work)
2. Evaluate and select papers

Review results considering citation count, relevance, recency, and open access availability. Present a summary and confirm which papers to retrieve.

3. Download and convert

For multiple papers (preferred): Save search results as JSON and use batch-fetch:

uvx opencite search "topic" --max 10 -f json -o results.json
uvx opencite batch-fetch --from-json results.json --convert -o ./papers --summary report.json

batch-fetch --convert automatically creates this directory structure:

papers/
├── pdf/          # downloaded PDFs
└── markdown/     # converted markdown files
    └── img/      # per-paper image directories (mistral only)

For individual papers:

uvx opencite pdf "10.1234/example" -o papers/pdf/ --convert

Note: pdf --convert places the markdown file next to the PDF and does not extract images. For the organized subdirectory layout with image extraction, use batch-fetch.

4. Read and synthesize

Read the converted markdown files for deeper analysis:

  • Summarize key findings across papers
  • Identify common themes and disagreements
  • When using batch-fetch, markdown is in papers/markdown/ and extracted images (markit-mistral only) are in per-paper subdirectories under papers/markdown/img/
  • Generate BibTeX for citation: uvx opencite lookup "DOI" -f bibtex --append-bib refs.bib

Command Summary

CommandPurpose
searchFind papers matching a query across multiple APIs
lookupLook up a specific paper by DOI, PMID, PMCID, or other identifier
citeGet citing/cited-by papers for a given identifier
canonicalFind the most-cited, foundational papers for a topic
pdfDownload a PDF for a paper by identifier
convertConvert a local PDF file to markdown
idsConvert between identifier types (DOI, PMID, PMCID)
batch-fetchDownload PDFs for multiple papers with optional conversion
configManage opencite configuration (init, show, path)

For full option listings, see references/cli-reference.md.

Configuration Essentials

Initialize configuration and check resolved values:

uvx opencite config init   # create ~/.opencite/config.toml template
uvx opencite config show   # display resolved config (keys masked)

Key environment variables:

  • SEMANTIC_SCHOLAR_API_KEY - Semantic Scholar API
  • PUBMED_API_KEY - NCBI/PubMed API
  • OPENALEX_API_KEY - OpenAlex API (required since Feb 2026)
  • MISTRAL_API_KEY - Enhanced PDF-to-markdown conversion (optional)

For full configuration details including publisher tokens and loading priority, see references/api-keys-and-config.md.

Error Handling

  • Rate limits: Semantic Scholar has aggressive rate limiting (1 req/sec). When rate limit errors occur, wait and retry.
  • Missing API keys: Commands warn about missing keys but still query available sources.
  • Timeouts: Retry the command or try a different source with --source.
  • PDF not found: opencite reports which sources were tried and why each failed. Papers behind paywalls may need institutional access or publisher API tokens.

References

Comments

Markdown supported