pubmed-search 0.6.0

CLI and Python SDK for biomedical literature search with MeSH, PICO, and intelligent query expansion

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="[e-mail]"
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:

Command	Purpose
search	Search biomedical literature across PubMed and optional academic sources.
strategy	Generate MeSH expansion and search strategy materials.
analyze-query	Analyze intent, complexity, identifiers, PICO, and source recommendations without running a search.
details	Fetch detailed metadata for one or more PMIDs.
export	Export citations as BibTeX, RIS, CSV, MEDLINE, CSL JSON, or JSON.
fulltext	Locate full-text access through available source resolvers.
text-mined	Retrieve text-mined biomedical terms when source data is available.
related	Find related articles for a PMID.
metrics	Fetch citation metrics where supported.
timeline	Build research timeline summaries from a query or PMID set.
cite-tree	Explore citation/reference relationships around a root PMID.
pico	Parse a clinical question into PICO-style components.
gene, compound, clinvar	Query NCBI extended databases.

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="[e-mail]")
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.