PubMed Search

CLI and Python SDK for biomedical literature search, query analysis, citation export, full-text lookup, and multi-source academic enrichment.

This repository is CLI/SDK-first. The primary runtime surface is the pubmed-search shell command, which is friendly to Codex-like coding agents, terminal workflows, and scripts. The Python package also exposes reusable clients and application services for projects that need direct imports.

Origin and Attribution

This CLI/SDK mainline is maintained at PiaoyangGuohai1/pubmed-search. It is derived from and inspired by u9401066/pubmed-search-mcp, with the Apache-2.0 license and upstream attribution preserved. The original MCP-oriented fork remains a legacy reference; this repository maintains the terminal and Python SDK surfaces.

Install

pip install pubmed-search

For local development from this repository:

pip install -e .

Optional NCBI credentials can be provided through flags or environment variables:

export NCBI_EMAIL="you@example.com"
export NCBI_API_KEY="optional_ncbi_key"

CLI

pubmed-search --help
pubmed-search search "MASLD cardiovascular risk" --format json --limit 5
pubmed-search strategy "MASLD cardiovascular risk" --format json
pubmed-search analyze-query "MASLD cardiovascular risk" --format json
pubmed-search details 38905512 --format markdown
pubmed-search export 38905512 --format ris
pubmed-search fulltext 38905512 --format markdown
pubmed-search timeline "MASLD cardiovascular risk" --limit 20 --format markdown

Core commands:

Use --format json for agent and script workflows. Use --output path to write command output directly to a file.

Python SDK

from pubmed_search import LiteratureSearcher, QueryAnalyzer, export_articles

searcher = LiteratureSearcher(email="you@example.com")
articles = searcher.search("MASLD cardiovascular risk", limit=5)

for article in articles:
    print(article["pmid"], article["title"])

analysis = QueryAnalyzer().analyze("MASLD cardiovascular risk")
print(analysis.intent, analysis.complexity)

bibtex = export_articles(articles, fmt="bibtex")

Useful imports include:

• LiteratureSearcher for PubMed search/details/citation metrics.
• SearchStrategyGenerator for MeSH and query strategy generation.
• QueryAnalyzer and ResultAggregator for application-level search planning.
• EuropePMCClient, NCBIExtendedClient, and source client factories for external data sources.
• export_articles, export_bibtex, export_ris, export_csv, export_medline, and export_json for citation output.

Architecture

The codebase keeps the retrieval product independent from any host application:

src/pubmed_search/
  cli/             click commands and terminal formatting
  application/     search planning, export, fulltext, timeline, and session services
  domain/          article and pipeline entities
  infrastructure/  NCBI, Europe PMC, OpenAlex, Semantic Scholar, Crossref, Unpaywall, and other adapters
  shared/          settings, logging, cache, and cross-cutting helpers

The CLI imports application services directly. Presentation-specific protocol servers are not part of the main package. If a protocol adapter is needed again later, it should live in a separate package that depends on pubmed-search.

Development

pip install -e .[all]
pytest
ruff check .

The editable package installs only the pubmed-search console command.

Citation

If you use this software in research or internal methods documentation, cite the repository metadata in CITATION.cff.