pubmed-stream

pubmed-stream: PubMed search and PubMed Central full-text download, for researchers and their AI assistants

pubmed-stream is an open-source Python library and command-line tool that takes a PubMed search to a knowledge graph of the literature. It is built on NCBI's official E-utilities API, works from the command line or Python, and needs nothing beyond requests. AI assistants use it too: it is a plugin for Claude Code and Codex, and a PubMed MCP server for them and Gemini CLI, so you can ask a research question in plain English and get an answer that cites only papers the assistant downloaded and read.

With it you can:

• Search PubMed and PubMed Central (PMC) with field tags and MeSH (Medical Subject Headings), and see how many papers a search finds before downloading anything (section 2)
• Bulk-download full-text articles from PubMed Central as JSON, with metadata, references and text or JATS XML, and the PubMed abstracts of articles without free full text (section 1)
• Export citations as BibTeX or RIS for Zotero, EndNote and Mendeley (section 1)
• Find the papers that cite a paper, the papers it cites and the papers PubMed rates as similar, with retracted papers, reviews and NIH funding flagged (section 3)
• Build a knowledge graph of a study's literature in Obsidian, one Markdown note per paper and MeSH concept, linked by citations, similarity and topics (section 4)
• Give AI assistants PubMed tools through the MCP server or the plugin, and summarize abstracts with a local LLM through Ollama, so nothing leaves your computer (section 5)
• Measure the impact of a retracted paper through the papers citing it and the papers citing those (tutorial 8)

Documentation: [melhzy.github.io/pubmed-stream](https://melhzy.github.io/pubmed-stream/), the tutorials, guides and reference in one searchable website, with every notebook shown with its results.

**A study made with it: the Aβ\*56 retraction impact page**, how a retracted Alzheimer's paper spread through the literature and how much of it language models learned, as an interactive page where every number comes from the study's files; see Studies.

New to programming? Start with tutorial 0, which takes a research question to a map of its literature in an afternoon. Click Open in Colab to run it in your web browser, with nothing to install; you only type your question into one settings cell.

flowchart LR

S["PubMed searches"] -->|"download"| D["Full-text articles metadata, references, text"] K["Key papers"] -->|"neighborhood"| N["Similar, citing and cited papers flagged reviews, retractions, NIH funding"] D --> G["Knowledge graph kg_topic, an Obsidian vault"] N --> G G --> O["Explore, write, refresh"]

Contents

• Quick start
• Tutorials
• Studies
• Installation and configuration
• 1. Download full-text articles from PubMed Central
• 2. Write PubMed searches that find the right papers
• 3. Map the evidence around a paper: citing, cited and similar articles
• 4. Build the knowledge graph of a study in Obsidian
• 5. Use it with AI assistants (MCP server and plugin), local models and Obsidian
• Python API for PubMed and NCBI E-utilities
• Troubleshooting
• How it works
• Contributing
• FAQ
• Citation, acknowledgments and license

Quick start

pip install pubmed-stream

Size a search and preview its newest titles, without downloading: it counts PMC and all of PubMed

pubmed-stream search '"gut microbiota"[Title] AND frailty[Title/Abstract]'

Download the full text of up to 50 articles, add the abstracts of those whose full text is not

free, then read them compactly

pubmed-stream download '"gut microbiota"[Title] AND frailty[Title/Abstract]' --max-results 50 pubmed-stream abstracts '"gut microbiota"[Title] AND frailty[Title/Abstract]' --max-results 200 pubmed-stream list publications --abstracts

Export them as citations for Zotero, EndNote or Mendeley

pubmed-stream export publications -o frailty.bib

Map the evidence around one paper: similar, citing and cited papers, with retractions flagged

pubmed-stream neighborhood 31319564

Build a study's knowledge graph in ./kg_gut_microbiome_frailty

pubmed-stream kg "gut microbiome frailty" -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' --seed 31319564

First add the folder in Obsidian with Open folder as vault, or use the automatic setup below.

After that, open the graph's home note from the terminal:

pubmed-stream open kg_gut_microbiome_frailty

Summarize the 10 newest abstracts and save the summaries in the knowledge graph. --model picks who

summarizes: a model on your own computer, in Ollama (https://ollama.com), so nothing leaves it, or the

model of an AI assistant installed below: claude, codex or gemini. Section 5 helps you choose

ollama pull qwen3.5:4b pubmed-stream review "Is the gut microbiota linked to frailty?" --limit 10 --model qwen3.5:4b --vault kg_gut_microbiome_frailty pubmed-stream review "Is the gut microbiota linked to frailty?" --limit 10 --model claude --vault kg_gut_microbiome_frailty

Or ask in plain English and let Claude Code, Codex or Gemini CLI run all of this: see below

For automatic first-time Obsidian setup with --register, see Open the graph in Obsidian. That section also explains how to use the updated source if your installed command does not yet support the option.

With an AI assistant: Claude Code, Codex or Gemini CLI

An AI assistant can do all of the above for you. Install one: Claude Code needs a paid Claude plan, Codex a paid ChatGPT plan, and Gemini CLI only a Google account. These commands need Node.js 22 or later; tutorial 7 shows the other installers and walks through a session.

npm install -g @anthropic-ai/claude-code   # Claude Code

npm install -g @openai/codex # Codex npm install -g @google/gemini-cli # Gemini CLI

Then give your assistant pubmed-stream's tools, in one of two ways:

# Claude Code or Codex: install the plugin once, for every folder. It needs uv (https://docs.astral.sh/uv/)

claude plugin install pubmed-stream --marketplace melhzy/pubmed-stream codex plugin marketplace add melhzy/pubmed-stream codex plugin add pubmed-stream@pubmed-stream

Any of the three: set up one research folder with the MCP server and instructions

mkdir gut_frailty cd gut_frailty pubmed-stream init

Start your assistant in your research folder with claude, codex or gemini. The first time, it asks you to sign in. With init, Claude Code also asks to approve the pubmed-stream server, and Gemini CLI asks whether you trust the folder: say yes to both, or the assistant will not have pubmed-stream's tools. /mcp lists them. Then ask in plain language:

*Is the gut microbiota linked to frailty? Size the search first, download the clinical studies, and summarize the evidence with PMIDs.*

Section 5 compares the plugin and init.

In Python

The first steps of the quick start, in Python:

from pubmed_stream import create_kg, get_neighborhood, search_and_download

stats = search_and_download('"gut microbiota"[Title] AND frailty[Title/Abstract]', max_results=50) hood = get_neighborhood("31319564") result = create_kg("gut microbiome frailty", queries=['"gut microbiota"[Title] AND frailty[Title/Abstract]'], seeds=["31319564"]) print(stats.successful, hood.totals, result.kg_dir)

Tutorials

The notebooks in tutorials/ are written for researchers, not programmers. Each follows a real research question. The notebooks have a single Your settings cell for your own question, run in Google Colab with nothing to install, and are saved with their results so you can read them first, on GitHub or on the documentation site; tutorial 7 happens in a terminal, with an AI assistant.

| 7 | Your literature search with an AI assistant | For medical students and biologists: install Claude Code or Codex, connect it to pubmed-stream's MCP tools with the plugin or pubmed-stream init, choose a model, ask in plain English, check the evidence, keep it in Obsidian,