pubmed-stream

pubmed-stream：研究者とその AI アシスタントのための PubMed 文献検索

PubMed 検索から、文献のナレッジグラフへ。 pubmed-stream は PubMed Central から全文論文をダウンロードし、重要な論文を取り巻くエビデンスをマッピングして、研究で収集したすべての情報を Obsidian のナレッジグラフにリンクします。そこでは、論文が引用、類似性、MeSH トピックを通じてつながります。NCBI の公式 E-utilities を基盤としており、コマンドラインまたは Python から利用でき、必要なのは requests だけです。AI アシスタントも利用できます。Claude Code と Codex のプラグインであり、Claude Code、Codex、Gemini CLI 向けの MCP サーバーでもあるため、英語で研究上の質問をするだけで、アシスタントがダウンロードして読み込んだ論文だけを引用する回答を得られます。

ドキュメント：melhzy.github.io/pubmed-stream。チュートリアル、ガイド、リファレンスをまとめた検索可能なウェブサイトで、すべてのノートブックに実行結果が表示されます。

このツールを使った研究：Aβ*56 論文撤回の影響ページ。撤回されたアルツハイマー病の論文が文献にどのように広がり、言語モデルがそのどれほどを学習したかを、すべての数値の出典を研究のファイルで確認できるインタラクティブなページで紹介しています。研究をご覧ください。

プログラミングが初めての方へ。 チュートリアル 0から始めましょう。研究上の質問から、その文献のマップを午後のうちに作成できます。Colab で開くをクリックすると、インストール不要でウェブブラウザー上で実行できます。設定セルに質問を入力するだけです。

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

目次

• クイックスタート
• チュートリアル
• 研究
• インストールと設定
• 1. 全文論文をダウンロードする
• 2. 適切な論文が見つかる検索式を書く
• 3. 論文を取り巻くエビデンスをマッピングする
• 4. 研究のナレッジグラフを構築する
• 5. AI アシスタント（MCP とプラグイン）、ローカルモデル、Obsidian で使う
• Python API
• トラブルシューティング
• 仕組み
• 貢献
• よくある質問
• 引用、謝辞、ライセンス

クイックスタート

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, then open it in Obsidian
pubmed-stream kg "gut microbiome frailty" -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' --seed 31319564
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

AI アシスタントを使う：Claude Code、Codex、Gemini CLI

AI アシスタントを使えば、上記の操作をすべて代わりに行えます。いずれかをインストールしてください。Claude Codeには有料のClaudeプラン、Codexには有料のChatGPTプランが必要ですが、Gemini CLIに必要なのはGoogleアカウントだけです。これらのコマンドにはNode.js 22以降が必要です。チュートリアル7では、ほかのインストーラーを紹介し、セッションの進め方を説明しています。

npm install -g @anthropic-ai/claude-code   # Claude Code
npm install -g @openai/codex               # Codex
npm install -g @google/gemini-cli          # Gemini CLI

次に、pubmed-streamのツールを次の2つの方法のいずれかでアシスタントに渡します。

# 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

claude、codex、geminiのいずれかを使って、研究用フォルダーでアシスタントを起動します。初回はサインインを求められます。initを実行すると、Claude Codeではpubmed-streamサーバーの承認も求められ、Gemini CLIではフォルダーを信頼するかどうか尋ねられます。どちらも「はい」と答えてください。そうしないと、アシスタントはpubmed-streamのツールを利用できません。/mcpでツール一覧を確認できます。次に、自然な言葉で質問します。

腸内細菌叢はフレイルと関連していますか？まず検索件数を見積もり、臨床研究をダウンロードして、PMIDとともにエビデンスを要約してください。

セクション5では、プラグインとinitを比較しています。

Pythonを使う

クイックスタートの最初の手順を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/内のノートブックは、プログラマーではなく研究者向けに作成されています。それぞれ、実際の研究課題に沿って進められます。ノートブックには独自の質問を設定するYour settingsセルが1つだけあり、何もインストールせずにGoogle Colabで実行できます。また、結果とともに保存されているため、GitHubまたはドキュメントサイトで、まず内容を確認できます。チュートリアル7は、AIアシスタントを使ってターミナルで行います。

#	チュートリアル	ユースケース
0	まずはこちら：午後のうちに新しい研究テーマを調べる	研究上の疑問から関連文献の全体像へ：研究分野の規模を把握し、誰もが引用する論文を見つけ、ナレッジグラフを作成し、テーマ、エビデンス、研究の空白を読み解き、文献リストをエクスポートします
1	はじめに	検索結果をダウンロードし、ファイルを読み、形式を選び、再開し、既知の論文を1件取得し、検索結果が見つからない場合に対処し、ダウンロードした内容をコンパクトに読みます
2	検索方法の設計	1つの検索方法の5つのバージョンについて規模、精度、利用可能性を測定し、キーワードとMeSH見出しを組み合わせます
3	文献レビュー用コーパス	キーワードリストを実行し、重複を除去し、テーマでスクリーニングし、CSVとBibTeXにエクスポートします
4	ある論文を取り巻くエビデンス	論文の周辺文献をマッピングし、撤回済み論文がないかスクリーニングします
5	研究のナレッジグラフ	グラフを作成し、12個のチャートと表で解説します
6	テキストマイニングとRAGの準備	論文をセクションに分割し、埋め込み用にチャンク化します
7	AI アシスタントを使った文献検索	医学生と生物学者向け：Claude CodeまたはCodexをインストールし、プラグインまたはpubmed-stream initを使ってpubmed-streamのMCPツールに接続し、モデルを選び、平易な英語で質問し、エビデンスを確認し、Obsidianに保存するか、Ollamaを通じてローカルモデルを使用します
8	撤回された論文の影響を測定する	Aβ*56に関する2006年のNature論文の撤回を起点に、その論文を引用した論文と、それらを引用した論文をたどります。いつ、どのように引用されているか、撤回後も誰が引用し続けているか、そしてその影響を示すナレッジグラフを調べます

5つの短いガイドがチュートリアルを補完します。

ガイド	対象
チュートリアルの実行方法	Colab、WindowsまたはMacへのPythonのインストール、ノートブックの実行、無料のNCBI APIキー
Obsidianでナレッジグラフを読む	グラフを開き、探索、検索、書き込みを行う方法
用語集	MeSH、PMC、スタブ、シードなど、あらゆる用語を平易な言葉で解説
pubmed-streamでできることとできないこと	網羅範囲、見落としやすい点、システマティックレビューではない理由
初心者向けトラブルシューティング	セットアップ、ノートブック、Colab、Obsidianの問題

チュートリアルのREADMEには、プログラマーがノートブックをローカルで実行する方法を含め、すべての情報が記載されています。

研究

pubmed-stream を使った研究は studies/ にあります。研究ごとにフォルダーが分かれており、固定したデータ、スクリプト、レポートと、ドキュメントサイトで公開された研究ページが含まれています。

研究	ページ	問い
Aβ*56 撤回の影響	ページを開く	チュートリアル 8 の続きです。Aβ*56 に関する、撤回された 2006 年の Nature 論文は、どの程度文献に広がったのでしょうか。論文を引用した 1,240 件の論文と、それらを引用した 44,957 件の論文を表として固定し、その論文が主張した内容と何が誤っていたのかを出典付きで説明しています。また、2 つのオープンな言語モデル学習コーパスにおける主張と訂正の件数、言語モデル向けの調査質問と最初の回答も掲載しています。

研究 README では、研究の構成と新しい研究の始め方を説明しています。

インストールと設定

pip install pubmed-stream                  # the library and the pubmed-stream command
pip install "pubmed-stream[tutorials]"     # plus jupyter, matplotlib, networkx and pandas for the tutorials

セクション 5 の AI アシスタント、ローカルモデル、Obsidian の機能にはバージョン 0.3.0 以降が必要です。PubMed の抄録と引用のエクスポートには 0.4.0、Claude Code、Codex、Gemini CLI によるレビュー（review --model claude）には 0.4.1、チュートリアル 8 でインポートされる Claude Code および Codex プラグイン pubmed_stream.impact と、init による NCBI API キーの保存には 0.4.2、MCP サーバーの進捗レポートと Windows でのコンソールウィンドウ非表示には 0.4.3 が必要です。pubmed-stream --version で現在のバージョンを確認でき、pip install --upgrade pubmed-stream で更新できます。クローンからは、pip install -e ".[dev]" を実行すると、pytest と ruff を含めて編集可能モードでインストールできます。pubmed-stream には Python 3.9 以降が必要です。実行時の依存関係は requests のみです。

NCBI API キーを設定します。 NCBI では、キーなしの場合は 1 秒あたり 3 件、キーありの場合は 10 件のリクエストが許可されるため、キーを使うとすべての処理がおよそ 3 倍速くなります。キーは無料です。NCBI アカウントの設定にある API Key Management で作成してください。各フォルダーで一度だけ保存します。

pubmed-stream init --ncbi-api-key "your-key"   # kept in ~/.pubmed-stream.json; init also asks for it while none is saved

init は保存前に NCBI でキーを確認します。保存済みのキーが NCBI に拒否された場合、pubmed-stream はその旨を知らせ、すべてのリクエストを失敗させるのではなく、キーなしで処理を続けます。キーがない場合、キーがあれば 10 秒以上短縮できたダウンロードでは、キーによって節約できた時間を最後に表示します。

pubmed-stream プラグインをインストールすると、Claude Code がキーを求めます。スクリプトやサーバーでは、任意の連絡先メールアドレスとともに環境変数を使うこともでき、その場合は環境変数が優先されます。

export NCBI_API_KEY="your-key"        # PowerShell: $env:NCBI_API_KEY = "your-key"
export NCBI_EMAIL="[email protected]"   # PowerShell: $env:NCBI_EMAIL = "[email protected]"

すべてのコマンドで --api-key と --email も指定できます。pubmed-stream はキーに応じてリクエストのレートを自動的に設定し、失敗したリクエストをバックオフしながら 3 回再試行します。また、キーをログに書き込むことはありません。必要に応じて --rate-limit SECONDS でさらに速度を落とせます。

1. 全文記事をダウンロードする

pubmed-stream download は PubMed Central を直接検索するため、検索結果はすべて PMC レコードを持つ記事です。その後、各記事の全文 XML を並列で取得し、1 つの JSON ファイルとして保存します。一部の出版社は記事の XML ダウンロードを許可していません。その場合は 利用不可 として報告され、内容が不完全なまま保存されるのではなく、スキップされます。

pubmed-stream download "gut microbiome" --max-results 50

from pubmed_stream import search_and_download

stats = search_and_download("gut microbiome", max_results=50)
print(f"{stats.successful} saved, {stats.skipped} already there, {stats.unavailable} unavailable "
      f"of {stats.total_found} matches, in {stats.duration_seconds:.0f} s")

検索ごとに、クエリを名前にした専用フォルダーが作成されます。名前が 100 文字を超える場合は短縮され、クエリの短いハッシュが末尾に付きます。同じ検索を再実行すると、すでに存在するファイルはスキップされるため、中断したダウンロードを再開できます。また、検索を繰り返した場合は新しいものだけが取得されます。

すべてのファイルを開かずにダウンロード内容を確認するには、list を実行します。記事ごとに 1 行が新しい順に表示され、複数の検索で見つかった記事も 1 回だけ表示されます。

pubmed-stream list publications                       # identifiers, year, title, journal, length
pubmed-stream list publications --id 31319564 --abstracts   # the abstracts of chosen articles
pubmed-stream list publications --cited               # the works the downloads cite most
pubmed-stream list publications --json --abstracts > corpus.jsonl

無料の全文がない記事。 PMC が無料の全文を収録しているのは文献の一部のみです。search は両方をカウントするため、クイックスタートのフレイルティ検索では、PubMed に 95 件の記事がある一方、PMC には 66 件あります。abstracts は各検索結果の PubMed レコードを、抄録、MeSH 用語、出版タイプとともに、全文と同じフォルダーに保存します。list、review、ナレッジグラフはどちらも読み込みます。list では抄録に [abstract only] の印が付き、全文と抄録の両方が保存されている記事は、全文とともに表示されます。

pubmed-stream abstracts '"gut microbiota"[Title] AND frailty[Title/Abstract]' --max-results 200
pubmed-stream kg "gut microbiome frailty" -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' --abstracts

from pubmed_stream import fetch_abstracts

stats = fetch_abstracts('"gut microbiota"[Title] AND frailty[Title/Abstract]', max_results=200)
print(f"{stats.saved} abstracts saved of {stats.total_found} in PubMed; {stats.in_pmc} are also free in PMC")

引用情報。 export は、記事、全文、抄録を BibTeX または RIS 形式で出力します。これらの形式は Zotero（File > Import）、EndNote、Mendeley、LaTeX で読み込めます。エントリーには、タイトル、著者、ジャーナル、年、DOI、PubMed ID、PMC ID、リンク、抄録が含まれます。各著者名の最初の語が姓として扱われるため、インポート後に「van der Berg」のような複数語の姓を確認してください。

pubmed-stream export publications -o review.bib
pubmed-stream export publications --format ris --id 38686220 41113141 -o chosen.ris

publications/
└── gut_microbiome/
    ├── query.json          the original search, recorded for later tools
    ├── PMC12345678.json    a full text from PMC
    ├── PMC12345679.json
    └── PMID41361501.json   an abstract from PubMed, saved by 'abstracts'

各記事ファイルの形式は共通です。metadata.references には、PubMed ID または DOI を持つ引用文献が一覧表示されます。これらはナレッジグラフの引用リンクになります。

{
  "pmcid": "PMC13279599",
  "source": "PMC",
  "download_date": "2026-10-18T13:20:45",
  "metadata": {
    "pmid": "42060019",
    "pmcid": "PMC13279599",
    "doi": "10.1007/s40520-026-03403-6",
    "title": "Association between gut microbiota and sarcopenia in older adults: ...",
    "journal": "Aging Clinical and Experimental Research",
    "year": "2026", "month": "4", "day": "30",
    "authors": ["Ramezani Kashal Fatemeh", "Sharifi Farshad", "..."],
    "abstract": "Introduction Investigating gut microbiota has emerged as a novel approach ...",
    "keywords": ["Sarcopenia", "Gut microbiota", "Aging", "Muscle metabolism"],
    "references": [
      {"pmid": "32033882", "doi": "10.1016/j.jamda.2019.12.012",
       "title": "Asian Working Group for Sarcopenia: 2019 Consensus Update ...", "year": "2020"}
    ],
    "linked_discoveries_url": "https://linkeddiscoveries.ncbi.nlm.nih.gov/42060019/"
  },
  "text": "Association between gut microbiota and sarcopenia ...\nAbstract\nIntroduction ..."
}

形式によって、メタデータとともに保存される内容が決まります。

--format	追加内容	最適な用途
text（デフォルト）	text：タイトル、抄録、本文。1 行につき 1 段落	読み込み、検索、埋め込み、ほとんどの NLP
xml	xml：生の JATS XML	セクション単位の解析、表、図
both	text と xml	あらゆる選択肢を残しておく場合

オプション	説明	デフォルト
QUERY	PubMed 検索。[Title] などのフィールドタグが使用可能	必須
--max-results N	ダウンロードする記事数。新しい順	100
--format	text、xml、both のいずれか	text
--exclude-text	容量を節約するため、text フィールドを除外	含める
--output-dir、-o	ベースフォルダー	./publications
--workers N、--sequential	並列ダウンロード、またはネットワークが不安定な場合に 1 件ずつダウンロード	5 ワーカー
--topic、--vault	結果をナレッジグラフにも追加します。セクション 4 を参照	オフ
--api-key、--email、--rate-limit、--user-agent、-v	NCBI の設定と詳細ログ	環境変数
--quiet	進行状況を表示せず、要約のみを出力	進行状況を表示

記事が保存されたか、すでに存在する場合、download は終了コード 0 を返します。検索結果がなかった場合は 1、すべてのダウンロードに失敗した場合は 2 を返します。

2. 適切な論文が見つかる検索式を作成する

PMC は、参考文献一覧を含むすべての記事の全文を検索するため、gut microbiome frailty のような単純な検索では、これらの語が本文中でたまたま言及されているだけの記事も何千件と一致します。フィールドタグを使えば、この問題を解消できます。チュートリアル 2では、1 つの質問に対する 5 種類の検索式を比較しています。関連性の高い最近の記事がほとんどない 7,587 件から、ほとんどがテーマに沿った 66 件まで絞り込めます。

手法	例	効果
中心となる概念をタイトルに限定する	"gut microbiota"[Title]	適合率が最も大きく向上します
残りの語句をタイトルと要旨に限定する	frailty[Title/Abstract]	本文中での偶発的な言及を除外します
複数語の用語を引用符で囲み、類義語を OR で網羅する	("gut microbiome" OR "gut microbiota")	再現率を損なわずにフレーズをまとめて検索できます
オープンアクセスに限定する	AND "open access"[filter]	すべての検索結果をダウンロードできます
年を限定する	AND 2020:2026[pdat]	最新の結果より少し前まで対象にするか、最新の結果に絞り込めます

PMC は新しい検索結果から順に返すため、--max-results では最も新しい論文が取得されます。ダウンロードする前に検索内容を確認しましょう。pubmed-stream search QUERY を実行すると、ダウンロードせずに件数と最も新しい論文のタイトルが表示されます。--show 0 を指定すると、件数のみが表示されます。

$ pubmed-stream search '"gut microbiota"[Title] AND sarcopenia[Title/Abstract]' --show 2
80 articles in PMC for: "gut microbiota"[Title] AND sarcopenia[Title/Abstract]
Newest 2:
  2026  PMC13668947  PMID 42875678  Correspondence for the article: "Association between gut microbiota and sarcopenia ...
  2026  PMC13641649  PMID 41879259  Alterations in the Gut Microbiota of Cirrhotic Patients With Sarcopenia and PH After TIPS. ...

3. 論文を取り巻くエビデンスをマッピングする

検索では、キーワードを使って論文を見つけます。エビデンス・ネイバーフッドは、1つの重要な論文を起点として、PubMedのリンクをたどります。PubMedが類似していると評価した論文、その論文を引用している論文、そしてその論文が引用している論文です。それぞれに、レビュー、撤回済み、NIHから資金提供を受けているかどうかが表示されます。NLMのLinked Discoveriesウェブツールにも同様のネイバーフッドが表示されますが、APIはありません。pubmed-streamは、文書化されたE-utilitiesを使ってネイバーフッドを構築します。

pubmed-stream neighborhood 9500320

Seed: PMID 9500320 (1998) Ileal-lymphoid-nodular hyperplasia, non-specific colitis, and ...
Similar       100            (4 reviews, 0 retracted, 0 NIH-funded, 18 in PMC)
Cited by      100 of 489     (145 reviews, 0 retracted, 52 NIH-funded, 421 in PMC)
References      0            (0 reviews, 0 retracted, 0 NIH-funded, 0 in PMC)
Neighborhood  200 unique articles fetched
[RETRACTED] PMID 9500320 (1998) Ileal-lymphoid-nodular hyperplasia, non-specific colitis, and ...
Saved: publications/neighborhood_9500320/neighborhood.json
Explore the graph: https://linkeddiscoveries.ncbi.nlm.nih.gov/9500320/

100 of 489は、489件のPubMed論文が起点となる論文を引用しており、そのうち新しい100件の詳細を取得したことを意味します。--max-per-relationでこの上限を変更できます。角括弧内の件数は、すべて489件を対象としており、全レコードをダウンロードするのではなくPubMed検索で数えたものです。[RETRACTED]には、取得した論文のうち撤回済みのものがすべて表示されるため、引用したり、これらを基に作業したりする前に確認してください。

フラグ	意味
review	出版物の種類がReview、Systematic Review、またはScoping Reviewです。ガイドラインやメタ分析も数えるPubMedのReviewフィルターより対象が絞られています
retracted	出版物の種類がRetracted Publicationであるか、撤回通知へのリンクがあります
NIH-funded	助成金リストにNIHの助成金があるか、出版物の研究支援の種類がN.I.H.です
in PMC	論文にPMC IDがあるため、全文をダウンロードできる可能性があります

ネイバーフッドはpublications/neighborhood_<PMID>/neighborhood.jsonに保存されます。--downloadを指定すると、全文がある起点論文とすべての近隣論文のPMC全文も同じ場所に保存されます。Pythonでは次のようにします。

from pubmed_stream import get_neighborhood, save_neighborhood, download_neighborhood

hood = get_neighborhood("31319564", max_per_relation=50)
print(hood.totals)                      # {"similar": 384, "cited_by": 239, "references": 139}
print(hood.flag_counts["cited_by"])     # reviews, retracted, NIH-funded and in-PMC counts across all of them

retracted = [a for a in hood.articles() if a.is_retracted]          # seed and neighbors
cites_retracted = [a for a in hood.references if a.is_retracted]    # does the paper cite retracted work?

save_neighborhood(hood)                 # publications/neighborhood_31319564/neighborhood.json
download_neighborhood(hood)             # PMC full text of the seed and its neighbors

各近隣論文は、pmid、title、journal、year、authors、pub_types、is_review、is_retracted、nih_funded、pmcid、doi、mesh_termsを持つRelatedArticleです。類似論文の場合は、類似度を示すscoreも含まれます。最大200件までのネイバーフッドではリクエストが2回必要で、上限に達して途中で打ち切られた関連ごとに5回追加されます。

Linked Discoveriesとの違いとして、類似度はBiomedBERTモデルではなくPubMedのSimilar Articlesアルゴリズムに基づくため、近隣論文が異なる場合があります。また、疾患、遺伝子、化学物質のフィルターはなく、引用リンクがあるのは参考文献リストが登録されている場合に限られ、その大半はPMC論文です。ウェブツールと同様、フラグは関連性を示すものであり、研究の妥当性を評価するものではありません。チュートリアル4では、ネイバーフッドをグラフ化し、撤回のスクリーニングを順を追って説明します。

neighborhoodは、成功時に0、PMIDが無効またはPubMedに存在しない場合に1、NCBIに接続できない場合に2で終了します。受け付けるのはPubMed IDです。これはpubmed.ncbi.nlm.nih.gov/<PMID>/というリンク内の番号、またはダウンロードした論文のmetadata.pmidであり、PMC IDではありません。

4. 研究のナレッジグラフを構築する

ダウンロードとネイバーフッドを組み合わせると、ナレッジグラフが作られます。研究にはトピック、その文献を収集する検索、そして必要に応じてネイバーフッドを含める重要な論文があります。pubmed-stream kgはこれらすべてを実行し、結果をkg_<topic>という名前のObsidianボルトにリンクします。これは論文、MeSH概念、コレクションごとに1つずつMarkdownノートを収めたフォルダーです。Open folder as vaultでObsidianに開くと、グラフビューに、どの論文が互いを引用しているか、またどのトピックを共有しているかが表示されます。

pubmed-stream kg "gut microbiome frailty" \
    -q '"gut microbiota"[Title] AND frailty[Title/Abstract]' \
    -q '"gut microbiota"[Title] AND sarcopenia[Title/Abstract]' \
    --seed 31319564 --max-results 25 --max-per-relation 30

この研究では、127件の論文からなるグラフが作られます。そのうち42件は全文付き、85件は起点となる論文のネイバーフッドから取得され、309件のMeSH概念にリンクしています。合計440件のノートです。研究内容は保存されるため、拡張し続け、トピックだけを指定すれば最新の状態を保てます。

pubmed-stream kg "gut microbiome frailty" -q "microbiome inflammaging"   # add a search
pubmed-stream kg "gut microbiome frailty" --add ./publications/old_query # add earlier downloads
pubmed-stream kg "gut microbiome frailty" --refresh                      # rerun everything, add new papers
pubmed-stream kg "gut microbiome frailty"                                # rebuild the notes only

downloadとneighborhoodも研究に加えることができます。--topic "gut microbiome frailty"を指定すると、その検索または起点論文が、kgで作成した場合と同様に記録されます。引数なしの--vaultを指定すると、クエリまたはネイバーフッドにちなんだ名前がグラフに付けられます。また、--vault DIRまたは--kg-dir DIRで任意のフォルダーを指定できます。Obsidianのリンクは1つのボルト内でしか機能しないため、研究の検索にはすべて同じトピックを指定してください。

グラフに含まれるもの

ノート	場所	リンク先
論文	papers/PMID<id>.md	引用している論文、引用されている論文、類似論文、MeSH概念、コレクション
概念	concepts/<MeSH heading>.md	その見出しでインデックス化された論文
コレクション	collections/Search - <query>.md、collections/Neighborhood - PMID <id>.md	その論文と主な概念
ホーム	PubMed Stream.md	コレクション、最もつながりの多い概念、撤回された論文

以下は、サンプル研究のグラフの一部です。グラフ内のリンクはすべて実在します。異なる検索で見つかった2026年の2件の研究が同じ2021年の研究を引用しており、PubMedはその研究をシードレビューの類似論文としても評価しています。このようなつながりは、検索結果のリストでは見えてきません。

flowchart LR
    C1["Search -<br/>gut microbiota AND sarcopenia"] --> P1["PMID 42060019<br/>gut microbiota and sarcopenia<br/>in older adults, 2026"]
    C2["Search -<br/>gut microbiota AND frailty"] --> P4["PMID 41601864<br/>gut microbiota and<br/>cognitive frailty, 2026"]
    C3["Neighborhood -<br/>PMID 31319564"] --> P2["PMID 31319564<br/>seed review, 2019"]
    C3 --> P3["PMID 33633246<br/>microbiota in patients<br/>with sarcopenia, 2021"]
    P1 -->|cites| P3
    P4 -->|cites| P3
    P2 -.->|similar| P3
    P1 --> M1(["Sarcopenia"])
    P1 --> M2(["Gastrointestinal Microbiome"])
    P3 --> M1
    P3 --> M2
    P2 --> M1
    classDef collection fill:#8E4EC6,stroke:#8E4EC6,color:#fff
    classDef stub fill:#8B8D98,stroke:#8B8D98,color:#fff
    classDef concept fill:#12A594,stroke:#12A594,color:#fff
    class C1,C2,C3 collection
    class P2,P3 stub
    class M1,M2 concept

リンク元は次のとおりです。

• 引用は、ダウンロードした論文の参考文献リスト（PMIDがある文献）と、近傍の引用・被引用論文から取得します。DOIしかない文献は、Other references の下に一覧表示されます。
• 類似性は、PubMedのスコアとともに近傍の類似論文から取得します。
• 概念はPubMedから取得するMeSH見出しです。200件の論文ごとに取得され、グラフにキャッシュされます。Humans や Aged などのチェックタグは論文のプロパティに保持されますが、ほぼすべての論文へのリンクになってしまうため、ノートは作成されません。
• スタブは、ダウンロードされなかった近傍の論文です。ノートにはPubMedの詳細とリンクが含まれ、pubmed/stub タグが付けられます。

論文ノートには、Obsidianのプロパティ、生成されたブロック、その後に自分のメモを書くスペースが含まれます。

---
type: "paper"
title: "Association between gut microbiota and sarcopenia in older adults: ..."
pmid: "42060019"
year: 2026
journal: "Aging Clinical and Experimental Research"
mesh:
  - "Sarcopenia"
  - "Gastrointestinal Microbiome"
status: "full-text"
tags:
  - "pubmed/paper"
---
%% pubmed-stream:start - generated; edits inside this block are overwritten %%
# Association between gut microbiota and sarcopenia in older adults: ...

**Published:** *Aging Clinical and Experimental Research* · 2026 · [PubMed](...) · [PMC](...) · [DOI](...)

## Abstract
## MeSH concepts
- [[Sarcopenia]] (major topic)
## Cites (39)
- [[PMID33633246|Alterations in intestinal microbiota diversity, composition, and function in patients with sarcop... (2021)]]
## Cited by (1)
%% pubmed-stream:end %%

## Notes

Your own notes go here and survive every rebuild.

安全に再構築できます。 再構築では、生成されたブロックとツールが管理するプロパティのみが置き換えられます。ブロック外のテキストや、Obsidianで追加したプロパティ、タグ、エイリアスは保持されます。また、変更されていないノートは書き換えられません。生成されたノートの名前を変更したり移動したりしないでください。再構築時に再作成されます。プロパティはObsidianの検索、Bases、Dataviewプラグインで利用できます。また、初回のビルド時にグラフビューに、撤回された論文、レビュー、スタブ、概念、コレクションを示す色が設定されます。

Tutorial 5では、この研究を構築し、グラフをチャートで解説します。論文の出所、どの概念が一緒に扱われるか、研究が最も依拠している論文、研究の各部分をつなぐ論文などを確認できます。

kg オプション	意味	デフォルト
TOPIC	研究テーマ。グラフは ./kg_<topic> に作成されます	必須
--query、-q	研究にダウンロードする検索。繰り返し指定できます	なし
--seed、-s	近傍を研究に加えるPMID。繰り返し指定できます	なし
--add DIR	以前にダウンロードしたフォルダーまたはファイル。繰り返し指定できます	なし
--refresh	記録されているすべての検索とシードを再実行します	新しいもののみ
--max-results、--max-per-relation	検索ごとの論文数、関係ごとの近傍数	100、100
--download-neighbors	スタブノートの代わりに、近傍の論文の全文をダウンロードします	スタブ
--fulltext	各論文の全文をノートに追加します	抄録のみ
--offline	キャッシュされたMeSH用語のみを使用します	不足分を取得
--kg-dir DIR	./kg_<topic> の代わりにグラフフォルダーを指定します	./kg_<topic>

すべて正常に完了すると kg は0で終了します。構築するものがない場合、またはオプションが無効な場合は1で終了します。検索または近傍の取得に失敗した場合は2で終了します。その場合も、残りの情報からグラフは構築されます。

把握しておくべき制限事項：

• MeSH 用語がない論文もあります。 インデックス登録には数か月かかり、MEDLINE 対象外のジャーナルに掲載された論文はインデックス登録されないため、そのような論文には概念リンクがありません。後日再構築すると、新たにインデックス登録された論文が反映されます。それ以外の論文は概念にリンクされませんが、引用リンクは保持されます。
• pubmed-stream 0.1.1 以前からダウンロードしたデータには、参照文献リストがありません。ただし、--format xml または both を指定して保存した場合は除きます。引用リンクを追加するには、再度ダウンロードしてください。
• PMID がない参照文献も多数あります。 会議論文、プレプリント、書籍はグラフではなく、その他の参照文献 に表示されます。
• ノートは削除されません。 ソースを削除しても、そのノートはグラフに残ります。

5. AI アシスタント、ローカルモデル、Obsidian で使う

pubmed-stream は、研究者が現在使っているツールに接続します。ターミナルで動作する AI アシスタント、すべてをコンピューター上に保持するローカルモデル、そしてナレッジグラフを保存する Obsidian です。

flowchart LR
    A["Claude Code, Codex,<br/>Gemini CLI"] -->|"MCP tools, from the plugin<br/>or pubmed-stream init"| P["pubmed-stream"]
    P --> K["kg_topic<br/>Obsidian vault"]
    P -->|"pubmed-stream review"| O["Ollama<br/>local model"]
    O -->|"review notes"| K
    A -->|"obsidian CLI"| K

Claude Code、Codex、Gemini CLI で pubmed-stream を使う（MCP）

仕組み。 MCP サーバーは Python ライブラリの一部です。コマンド pubmed-stream mcp で起動します。他にインストールするものはありません。AI アシスタントがこのコマンドをバックグラウンドで起動すると、以降は、あなたがコマンドを入力するのと同じように、pubmed-stream のツールを自分で呼び出せるようになります。設定では、サーバーの起動方法だけをアシスタントに伝えます。その方法は3つあり、ライブラリの取得元と、どのフォルダーでツールを使えるかだけが異なります。

flowchart LR
    L["The pubmed-stream library<br/>(PyPI)"]
    L -->|"uv fetches it"| P["The plugin<br/>Claude Code, Codex<br/>every folder"]
    L -->|"pip install"| I["pubmed-stream init<br/>all three assistants<br/>one folder"]
    L -->|"pip install"| M["claude / codex mcp add<br/>every folder"]
    P --> S["pubmed-stream mcp<br/>the MCP server"]
    I --> S
    M --> S
    S -->|"9 tools"| A["The assistant"]

1. どのフォルダーでも Claude Code または Codex で使えるプラグイン。 plugins/pubmed-stream にあるプラグインにはコードは含まれていません。アシスタントに uvx --from pubmed-stream==<version> pubmed-stream mcp でサーバーを起動するよう指示する、いくつかの設定ファイルで構成されています。uv が PyPI からそのリリースのライブラリをダウンロードして実行するため、pip install は不要です。プラグインのバージョンには、実行するライブラリのリリースが常に指定されています。また、literature-search スキルとして手順も含まれています。uv をインストールしてから、次のコマンドを実行してください。

claude plugin install pubmed-stream --marketplace melhzy/pubmed-stream   # Claude Code; asks for your NCBI API key

codex plugin marketplace add melhzy/pubmed-stream                         # Codex
codex plugin add pubmed-stream@pubmed-stream

初回起動時は uv が pubmed-stream をダウンロードするため、時間がかかります。アシスタントからサーバーが起動しなかったと報告された場合は、アシスタントを再起動してください。Claude Code が NCBI API キーを尋ねなかった場合は、Claude Code 内で /plugin configure pubmed-stream@pubmed-stream と入力してください。

2. 1つの研究フォルダーで3つのアシスタントのいずれでも使える pubmed-stream init。 pip install pubmed-stream の後、フォルダー内で実行してください。ライブラリがインストールされている Python を使ってサーバーを起動する設定ファイル、python -m pubmed_stream mcp を書き込みます。Claude Code 用の .mcp.json、Codex 用の .codex/config.toml、Gemini CLI 用の .gemini/settings.json が作成されます。また、AGENTS.md に手順を書き込み、CLAUDE.md と GEMINI.md からそれをインポートします。さらに、NCBI API キーを一度だけ尋ねます。init --claude-model opus と init --review-model <ollama model> で、フォルダーのモデルを選択できます。

cd my_research_folder
pubmed-stream init

3. プラグインを使わず、各フォルダーに手動で設定する方法。 pip install pubmed-stream の後、コマンドを一度登録してください。--scope user を指定すると、コマンドを実行したフォルダーだけでなく、Claude Code がすべてのフォルダーで読み込みます。アシスタントはツールを使えるようになりますが、手順ファイルは読み込みません。そのため、最初の2つの方法のいずれかをおすすめします。

claude mcp add --scope user pubmed-stream -- pubmed-stream mcp
codex mcp add pubmed-stream -- pubmed-stream mcp

使い始める。 研究フォルダーで claude、codex、または gemini を起動してください。ダウンロードしたファイルはそのフォルダーに保存されます。/mcp と入力して、pubmed-stream がツールとともに一覧に表示されることを確認し、自然な言葉で研究上の質問をしてください。

パーキンソン病の患者に対して、糞便微生物叢移植は有効ですか？ 臨床エビデンスを探し、PMID とともに要約してください。 アシスタントは、9 つのツールから自動的に選びます。各ツールが簡潔なテキストを返すため、全文 4.3 MB を読む代わりに、約 3,000 トークンで 64 本の論文をスキャンできます。指示では、ダウンロード前に検索規模を確認し、セッション中にダウンロードして読んだ論文だけを引用すること、各論文がどのような種類のエビデンスなのかを説明すること、検索と件数を報告すること、読めなかったものを明記することを求めています。数百件の記事やナレッジグラフのダウンロードには数分かかります。実行中、サーバーは進捗を報告し、Claude Code に表示されます。

アシスタントに選ばせず、意図的に pubmed-stream を呼び出すには：

場所	入力する内容
Claude Code：ターミナル、VS Code、JetBrains、Claude デスクトップアプリの Code タブ	/pubmed-stream と入力すると、メニューが /pubmed-stream:literature-search に絞られます。これを選び、質問を追加します
Codex アプリ	/ または @ を入力し、pubmed-stream を選びます
Codex CLI	$pubmed-stream:literature-search と入力するか、/skills から選びます
Gemini CLI	init でセットアップしたフォルダーで質問します。スキルメニューはありません
Cowork（Claude デスクトップアプリ内）	まず、claude.ai アカウントにプラグインを追加します：Customize > Plugins > Add > Add marketplace を選び、melhzy/pubmed-stream を入力してから、pubmed-stream を追加します。Cowork はコンピューター上でサーバーを起動するため、uv のインストールが必要です。次に / を入力して、pubmed-stream の下に表示される literature-search を選ぶか、そのまま質問します。このプラグインはアカウント経由で Claude Code からも利用できます。ターミナル版がインストールされている場合、Claude Code は引き続きそちらを使います
Claude デスクトップアプリのチャット	Claude Code と Cowork だけが起動できるプラグイン経由では利用できません。代わりに、チュートリアル 7、オプション C のように、アプリの設定にサーバーを追加すると、チャットからそのツールを呼び出せます
Claude のウェブ版およびスマートフォン版チャット	利用できません。これらの環境では、コンピューター上のプログラムを起動できません。アカウントにプラグインを追加すると、/ でそのスキルが表示されますが、呼び出せるツールはありません

ツール	アシスタントによる使い方
search_pmc	ダウンロードせずに、PMC 検索の件数を数え、最新の一致結果を一覧表示します
download	検索結果の全文をダウンロードします。論文ごとに 1 つの JSON ファイルが作成されます
fetch_abstracts	無料の全文がない論文も含め、PubMed の抄録を保存します
list_articles	ダウンロード済みの論文を、必要に応じて抄録も付けて簡潔に一覧表示します
most_cited	ダウンロードした論文が最も多く引用している文献を見つけます
read_article	論文全体、または指定した用語を含む段落だけを読みます
neighborhood	1 つの PMID に関連する類似論文、引用論文、被引用論文をマッピングし、撤回を明示します
export_citations	Zotero、EndNote、Mendeley 用の BibTeX または RIS を書き出します
build_knowledge_graph	ある研究の検索結果と主要論文を Obsidian の保管庫にリンクします

それぞれの方法は競合しません。プラグインがインストールされている場合、init はサーバーをフォルダーに追加しないため、ツールが二重に表示されることはありません。また、すでにセットアップ済みのフォルダーで再実行すると、重複分が削除されます。

ローカルモデルと Obsidian

ローカルモデル。 企業に送信したくない質問には、pubmed-stream review を使うと、選択した抄録を自分のコンピューター上の Ollama で実行するモデルに要約させることができます。コンピューターの外に出るのは PubMed 検索だけです。モデルは抄録を一度に 1 つずつ、温度 0 で読み、質問を見ることはないため、質問を研究結果として提示することはありません。pubmed-stream は各 PubMed ID を自動で付与し、抄録が裏付けていない数値や引用にはフラグを付けます。

1. Ollama をインストールします。 ollama.com/download からダウンロードするか、Windows では winget install Ollama.Ollama を実行します。バックグラウンドで動作します。ollama list を実行して、正常に動作することを確認します。 2. お使いのコンピューターで実行できるモデルを選びます。 Ollamaのライブラリにあるモデルならどれでも使えます。Qwen、Gemma、Llamaなどのオープンウェイトモデルも含まれます。pubmed-streamは、「思考」ステップがあるモデルではこれを無効にするため、要約の文字数を消費しません。大きなモデルほど間違いは少なくなりますが、より多くのメモリが必要です。モデルのダウンロードサイズは、コンピューターのメモリの約3分の2以下を目安にしてください。また、グラフィックカードのメモリに収まるモデルは、はるかに高速に動作します。

お使いのコンピューター	モデルサイズ	例（ダウンロードサイズ）
どのノートパソコンでも、メモリ8 GB	10億～40億パラメーター	llama3.2:3b（2.0 GB）、qwen3.5:4b（4.0 GB）
メモリ16 GB、またはメモリ8 GBのグラフィックカード	80億～120億	qwen3.5:9b（7.6 GB）、gemma4:12b（7.7 GB）
メモリ32 GB、またはメモリ16～24 GBのグラフィックカード	260億～350億	gemma4:26b（16 GB）、qwen3.5:27b（20 GB）

--modelを指定しない場合、reviewはLlama 3.2 1B（807 MB）を使用します。ほとんどのコンピューターで動作しますが、間違いは増えます。パーキンソン病に関する7本の論文では、11件の研究をまとめたレビューをランダム化比較試験と誤認しましたが、Qwen3.5 2Bではその誤りはありませんでした。

3. モデルをダウンロードして、次のように実行します。

ollama pull qwen3.5:9b
pubmed-stream review "Does FMT help people with Parkinson's disease?" --id 38686220 41826284 41113141 --model qwen3.5:9b --vault kg_fmt_parkinson

--vaultを指定すると、要約はナレッジグラフのreviewsフォルダーにもノートとして保存されます。ノート名には質問、日付、モデルが含まれるため、複数のモデルによるレビューを並べて確認できます。pubmed-stream init --review-model qwen3.5:9bを実行すると、このモデルがフォルダーのデフォルトになり、--modelを省略できます。--answerを指定すると、すべての要約をもとに1つの回答が追加されます。小型モデルは誤った論文に知見を結び付けることがあるため、回答は要約と照らし合わせて確認してください。Ollamaがラボのサーバーなど別のコンピューターで動作している場合は、--ollama-host http://<server>:11434で接続先を指定します。

または、AI アシスタントのモデルを使います。 --model claude、--model codex、または--model geminiを指定すると、Claude Code、Codex、またはGemini CLIが代わりに要約します。これらがコンピューターにインストールされ、サインイン済みである必要があります（クイックスタートを参照）。各モデルはノートパソコンで実行できるモデルよりはるかに大きいため、間違いが少なくなります。上記のパーキンソン病に関する7本の論文では、Claude Codeの要約はすべて正確でした。Llama 3.2 1Bが試験と誤認した11件の研究をまとめたレビューも正しく要約できました。その代わり、抄録はAnthropic、OpenAI、またはGoogleに送信され、実行のたびに利用プランの枠が消費されます。pubmed-streamは空のフォルダーでツールを無効にした状態でアシスタントを実行するため、アシスタントは回答だけを行います。それ以外はOllamaと同じです。質問なしで抄録を1件ずつ処理し、同じチェック、--answer、--vaultを使用できます。--model claude:opusのように、コロンの後にアシスタント側のモデルを指定します。

pubmed-stream review "Does FMT help people with Parkinson's disease?" --id 38686220 41826284 41113141 --model codex --vault kg_fmt_parkinson

--model	要約するもの	抄録の送信先
qwen3.5:9bなどのOllamaモデル	お使いのコンピューター上のモデル	送信なし
claude、claude:opus	Claude Code	Anthropic
codex、codex:<model>	Codex	OpenAI
gemini、gemini:<model>	Gemini CLI	Google

Obsidian。 すべてのナレッジグラフには、ObsidianとPapers.base用のプロパティタイプが含まれます。Papers.baseはすべての論文を一覧表示するBasesテーブルで、全文、レビュー、撤回された論文、#to-readリストのビューがあります。pubmed-stream open kg_<topic>で開くことができ、Obsidianのコマンドラインを有効にすると、アシスタントからクエリを実行できます。例：obsidian vault=kg_<topic> base:query path=Papers.base view="Reading list"。

Tutorial 7では、実際のセッションを紹介しています。アシスタントが検索結果4,863件から引用付きレポートを作成する例、Claude CodeとCodexがMCPツールを使う例、そして10億パラメーターのローカルモデルが正しく処理できることと間違えることを説明しています。この規模のモデルは要約は得意ですが、自分で検索を実行することはできません。

Python API

各コマンドでできることは、すべてpubmed_streamから利用できます。

関数	目的	戻り値
search_and_download(query, max_results, fmt="text", ...)	PMC を検索し、全文をダウンロードします	DownloadStats
get_neighborhood(pmid, max_per_relation=100, ...)	類似論文、引用論文、被引用論文をフラグ付きで取得します	Neighborhood
save_neighborhood(hood, output_dir=None)	neighborhood.json を書き込みます	パス
download_neighborhood(hood, ...)	起点論文と近傍論文の全文をダウンロードします	DownloadStats
create_kg(topic, queries, seeds, sources, refresh=False, ...)	調査を実行し、ナレッジグラフを構築します	KGResult
load_study(kg_dir), record_study(kg_dir, topic, queries, seeds)	グラフに記録された調査を読み込む、または追加します	dict
build_vault(sources, vault_dir, ...)	ダウンロードフォルダーのみからグラフのノートを構築します	VaultStats
topic_vault_dir(topic)	トピックの kg_<topic> フォルダーを取得します	パス
search_pmc(query, max_results=10, ...)	ダウンロードせずに検索件数を数え、最新の一致結果を一覧表示します	SearchResult
count_pubmed(query)	検索条件に一致する PubMed 論文の数を取得します	int
fetch_abstracts(query, max_results=100, ...)	無料の全文がない論文も含め、PubMed の抄録を保存します	AbstractStats
list_articles(path)	ダウンロードした論文と抄録の簡潔な記録を、新しい順に重複なく取得します	list of dicts
export_citations(path, fmt="bibtex", ids=None), to_bibtex(records), to_ris(records)	Zotero、EndNote、Mendeley 用の引用情報を取得します	(text, count, missing), str
most_cited(path, n=10)	ダウンロードした論文が最も多く引用している文献を取得します	list of dicts
review(question, path, ids, model, answer=False, ...)	Ollama 経由のローカルモデル、または claude、codex、gemini による要約をチェック付きで取得します	Review
init_folder(folder)	Claude Code、Codex、Gemini CLI 用の手順と MCP 設定を用意します	list of actions
open_vault(kg_dir)	Obsidian でナレッジグラフを開きます	(opened, message)
esearch_pmc(term, max_results, api_key, session, rate_limiter)	PMC を 1 回検索し、ID と合計件数を取得します	(ids, total)
esummary_pmc(pmcids, api_key, session, rate_limiter)	PMC 論文のタイトル、ジャーナル、出版年、識別子を取得します	list of dicts
efetch_pmc(pmcid, out_dir, fmt, api_key, session, rate_limiter)	論文を 1 件ダウンロードします	(ok, status)
extract_metadata_from_pmc_xml(xml), extract_text_from_pmc_xml(xml)	手元にある JATS XML を解析します	dict, str
create_session(user_agent), RateLimiter(seconds)	低レベル関数を構成する部品です

NCBI を呼び出す関数は api_key、email、user_agent、rate_limit を受け取り、再利用する session も指定できます。これらが指定されていない場合は、環境変数を使用します。低レベル関数には、明示的なセッションとレートリミッターを渡します：

from pathlib import Path
from pubmed_stream import RateLimiter, create_session, efetch_pmc, esearch_pmc

session, limiter = create_session("my-project/1.0"), RateLimiter(0.34)
ids, total = esearch_pmc('"gut microbiota"[Title] AND frailty[Title/Abstract]', 20, None, session, limiter)
for pmc_id in ids:
    ok, status = efetch_pmc(pmc_id, Path("downloads"), "both", None, session, limiter)   # success, unavailable, exists or error

論文が文献の中でどのように広まったかは、専用のモジュール from pubmed_stream import impact で測定します。impact.citers_of(pmids) は、多数の論文を引用する記事を PubMed に一度に問い合わせます。impact.count_by_year(pmids, first, last) と impact.count_flags(pmids) は、記事の記録をダウンロードせずに、年別、またはレビュー、撤回済み、NIH 助成対象の別に件数を数えます。また、impact.corrections(pmid) は、論文の撤回通知、正誤表、コメントを一覧表示します。impact.citation_contexts(folder, pmid, doi) は、ダウンロード済みの各全文でその論文を引用している文を探します。impact.semantic_scholar_contexts(pmid) は、全文が無料で公開されていない論文について、Semantic Scholar が保有する文を追加します。impact.classify(sentences) は、それらを論文の撤回や疑念について述べているもの、研究結果を示しているもの、一般的な引用に分類します。impact.annotate(kg_dir, properties) は、結果をナレッジグラフのノートに書き込みます。チュートリアル 8 では、撤回された論文を起点に、引用論文を 2 ホップたどります。

トラブルシューティング

症状	原因と対処法
Windows で引用符で囲んだフレーズが無視される	Windows PowerShell 5.1 は内側の二重引用符を削除し、コマンド プロンプトは単一引用符を認識しません。PowerShell では '\"gut microbiota\"[Title] AND frailty[Title/Abstract]' と入力します。コマンド プロンプトでは "\"gut microbiota\"[Title] AND frailty[Title/Abstract]" と入力します。PowerShell 7.3 以降、macOS、Linux では、例をそのまま使用できます
0 件保存されたが、該当件数は多い	ファイルはすでに存在していたためスキップされており、これは成功としてカウントされます。stats.skipped に表示されます
利用できない 論文が多い	論文の出版社が XML のダウンロードを許可していません。検索に AND "open access"[filter] を追加してください
HTTP 429、リクエストが多すぎます	リクエストは自動的に再試行されます。NCBI API キーを追加する（pubmed-stream init --ncbi-api-key）か、--rate-limit 0.5 で速度を落としてください
NCBI に API キーを拒否された	保存したキーに誤りがあるか、取り消されています。pubmed-stream はキーなしで処理を続けます。NCBI アカウント設定でキーを作成し、pubmed-stream init --ncbi-api-key で再度保存してください
タイムアウト、または不安定なネットワーク	--sequential を使用するか、--workers の数を減らしてください
アシスタントに pubmed-stream のツールが二重に表示される	プラグインをインストールする前に、init でフォルダーをセットアップしています。そのフォルダーで pubmed-stream init をもう一度実行してください。プラグインがインストールされている場合、フォルダー独自のサーバーは削除されます
プラグインのサーバーが起動しなかった	初回起動時は uv 経由で pubmed-stream をダウンロードするため、アシスタントの待ち時間を超えることがあります。アシスタントをもう一度起動してください。失敗が続く場合は、uv がインストールされていない可能性があります
アシスタントが別の PubMed ツールを使用した	Claude Code に Anthropic の PubMed コネクターも接続されている場合があり、どちらも文献に関する質問に回答できます。論文をフォルダーに保存したい場合は「pubmed-stream を使って」と伝えるか、claude.ai の設定でコネクターをオフにしてください
Windows でデスクトップアプリが pubmed-stream を起動すると、コンソールウィンドウが開く	デスクトップアプリにはコンソールがないため、Windows がサーバー用にコンソールを開き、アプリはそのウィンドウを画面に残します。pubmed-stream 0.4.3 以降では、サーバーの起動後すぐにウィンドウを非表示にするため、一瞬だけ表示されます。操作するのは、自身のプロセスだけが存在するコンソールに限られ、ターミナルには触れません
質問と無関係な検索結果	検索では論文内のあらゆる場所にあるテキストが一致します。セクション 2 を参照してください
'PMC…' は PMC ID です	neighborhood と --seed には PubMed ID が必要です。ダウンロードしたファイルでは metadata.pmid に記載されています
近傍に含まれる参考文献や引用が少ない	NCBI に引用リンクがあるのは、参考文献リストが登録された論文のみで、その大半は PMC の論文です
グラフに概念リンクがない論文	PubMed でまだ MeSH インデックスが作成されていません。後で再構築してください

Python、Jupyter、Colab、Obsidian のインストールに関する問題は、初心者向けトラブルシューティングガイドで取り上げています。

詳細を確認するには、任意のコマンドに -v を追加するか、このパッケージのみのデバッグログを有効にしてください。HTTP ライブラリのデバッグ出力を有効にすると、API キーを含むリクエスト URL がログに記録されるためです。

import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("pubmed_stream").setLevel(logging.DEBUG)

仕組み

pubmed-stream は、5 つの小さなモジュールで構成されています。コマンドラインから HTTP クライアントまで、各モジュールが利用するのは下位のモジュールだけです。

モジュール	役割
cli.py	pubmed-stream コマンド：init、search、download、abstracts、list、export、neighborhood、kg、review、open、mcp
corpus.py	ダウンロードした論文と抄録をコンパクトなレコードとして読み込み、最も多く引用されている研究を見つけます
export.py	BibTeX と RIS の引用情報
abstracts.py	無料の全文がない論文を対象とした、PubMed の検索と抄録の取得
mcp_server.py	AI アシスタントに pubmed-stream のツールを提供する MCP サーバー
review.py	Ollama 経由のローカルモデルまたは AI アシスタントによる要約と、数値および引用のチェック
obsidian.py、assistants.py	Obsidian でグラフを開く機能、AI アシスタント用フォルダーのセットアップ
settings.py	~/.pubmed-stream.json に保存される NCBI API キーと、各フォルダーの設定
impact.py	論文が文献に与えた影響：年ごとの引用論文、引用文、注釈
kg.py	研究：検索とシードの実行、記録、更新
vault.py	ナレッジグラフのノート：すべてのソースの統合、ノートのレンダリング、安全な再構築
neighborhood.py	類似論文、引用論文、被引用論文と、フラグおよび MeSH 用語
downloader.py	E-utilities クライアント、PMC の検索とダウンロード、JATS の解析

アーキテクチャガイドでは、図、表、挿絵を使ってリポジトリ全体を説明しています。すべての NCBI リクエスト、リクエストのフロー、ナレッジグラフの統合と安全な再構築の方法、データモデル、コードの拡張箇所を確認できます。

pubmed-stream/
├── pubmed_stream/      the package
├── tests/              163 offline tests; NCBI is faked with canned responses
├── tutorials/          eight notebooks, the AI assistant tutorial and instructions, guides, kg_study.py, keyword lists, tools
├── plugins/            the Claude Code and Codex plugin: MCP server settings and the literature-search skill
├── .claude-plugin/     the Claude Code marketplace that lists the plugin
├── .agents/plugins/    the Codex marketplace that lists the plugin
├── docs/               the architecture guide and its figures
├── pyproject.toml      package metadata and dependencies
├── server.json         the MCP server's entry in the official MCP Registry
├── studies/            research done with pubmed-stream, with its frozen data; see studies/README.md
├── CHANGELOG.md        changes in each version
├── CITATION.cff        how to cite pubmed-stream
└── LICENSE             MIT

貢献

貢献を歓迎します。リポジトリをフォークし、機能ブランチを作成して、プルリクエストを送ってください。新しい動作にはテストを追加し、pytest と ruff check . がパスすることを確認してください。GitHub Actions はすべてのプルリクエストで両方を実行します。テストはオフラインで数秒で実行できます。

pip install -e ".[dev]"
pytest

ドキュメントサイトは README、tutorials/、docs/、変更履歴からビルドされ、main へのプッシュごとに GitHub Actions によって公開されます。次のコマンドで http://127.0.0.1:8000 にプレビューできます。

pip install -r docs/requirements.txt
mkdocs serve

今後のロードマップ案：検索クエリビルダーとプログレスバー。

PyPI へのリリース

メンテナーは新しいバージョンを手動で公開します。X.Y.Z を新しいバージョンに置き換えてください。

1. pubmed_stream/__init__.py（__version__ = "X.Y.Z"）のバージョンを更新します。pyproject.toml はここからバージョンを読み込みます。また、CITATION.cff の version と date-released も更新します。プラグインでは、plugins/pubmed-stream 内の両方の plugin.json ファイルの version、リリース時にサーバーが実行するバージョン（.codex-plugin/mcp.json と .claude-plugin/plugin.json の pubmed-stream==X.Y.Z）、スキルの注記（2か所）、および server.json の2か所（version とパッケージの version）を更新します。変更履歴の Unreleased 見出しを X.Y.Z - YYYY-MM-DD に変更します。更新漏れがある場合はテストで検出されます。

2. テストを実行します：pytest。

3. 配布物をビルドして確認します。dist/ は Git の追跡対象外です。

   pip install --upgrade build twine
   rm -rf dist build *.egg-info
   python -m build
   python -m twine check dist/*
   

4. PyPI にアップロードします。https://pypi.org/manage/account/token/ で取得した、pubmed-stream プロジェクトにスコープを限定した API トークンを使用します。ユーザー名には文字どおり __token__ を指定します。PyPI のパスワードは使用できません。403 Forbidden が表示される場合、トークンが間違っているか、期限切れか、このプロジェクトにスコープ設定されていません。PyPI では同じバージョンを二度受け付けないため、リリースに問題があった場合は、新しいパッチバージョンで修正します。InvalidDistribution: Metadata is missing required fields: Name, Version は、twine が古く、パッケージのメタデータ（バージョン 2.4）を読み取れないことを意味します。twine 6.1 以降を使用してください。Anaconda のような共有環境で twine をアップグレードすると、そこで他のツールが依存しているパッケージもアップグレードされるため、別の仮想環境から実行してください。

   python -m twine upload -u __token__ dist/*
   

   twine に求められたらトークンを貼り付けてください。入力したトークンはシェルの履歴に残りません。リリースをプッシュする前にアップロードしてください。GitHub 上のプラグインは、pubmed-stream==X.Y.Z で指定されたリリースを実行するため、PyPI にそのリリースが登録されるまでは、プラグインのサーバーを起動できません。

5. リリースをコミットし、タグ付けしてプッシュします。

   git commit -am "chore: Release X.Y.Z"
   git tag X.Y.Z
   git push origin main X.Y.Z
   

   タグがすでに誤ったコミットに付けられている場合は、タグを移動して、そのタグだけを強制プッシュします。main は決して強制プッシュしないでください。git tag -f X.Y.Z <commit> を実行し、続けて git push --force origin refs/tags/X.Y.Z を実行します。

6. GitHub リリースを作成します。 Web インターフェースで https://github.com/melhzy/pubmed-stream/releases/new?tag=X.Y.Z を開き、タイトルを X.Y.Z に設定し、CHANGELOG.md の該当バージョンのセクションを説明として貼り付け、dist/ にある2つのファイルを添付して公開します。GitHub CLI を使う場合は、初回に gh auth login を実行した後、gh release create X.Y.Z --title "X.Y.Z" --notes "<the changelog section>" dist/* を実行します。

7. 公式 MCP Registry の掲載情報を更新します。他の MCP ディレクトリはこの情報をコピーします。登録されるのは server.json のみなので、PyPI にリリースが登録された後に実行してください。レジストリは、そのバージョンが PyPI に存在することと、PyPI に表示される README に mcp-name: io.github.melhzy/pubmed-stream という行が含まれていることを確認します。この行は README に隠しコメントとして記載されています。mcp-publisher をインストールした状態で、リポジトリのルートから次を実行します。

   mcp-publisher login github   # once; it signs in as the GitHub account that owns melhzy/pubmed-stream
   mcp-publisher publish
   

8. 確認します：pip install --upgrade pubmed-stream を実行し、続けて pubmed-stream --version を実行します。

FAQ

PubMed と PMC の違いは何ですか？ PubMed は 3,500 万件を超える論文の引用情報と抄録を索引化しています。PubMed Central（PMC）は、NCBI の全文論文アーカイブで、その一部が収録されています。pubmed-stream は PMC から全文をダウンロードし、周辺情報や MeSH 用語、全文が無料で入手できない論文の抄録には PubMed を使用します。

NCBI の利用規約に準拠していますか？ はい。公式の E-utilities を使用し、NCBI のレート制限を守り、User-Agent で自身を識別し、連絡先メールアドレスを設定している場合はそれを送信します。

論文ごとに JSON ファイルが 1 つなのはなぜですか？ 1 つのファイルに、どの形式でも論文のメタデータ、参考文献、本文をまとめられるため、コーパスのフィルタリング、統合、再開が簡単になります。

中断したダウンロードを再開できますか？ はい。同じコマンドをもう一度実行してください。既存のファイルはスキップされます。

システマティックレビューに利用できますか？ 初期段階、つまり分野の範囲設定、検索のテストと記録、重要な論文の特定には利用できます。システマティックレビューには、他のデータベース、2 名のレビュー担当者によるスクリーニング、バイアスリスクの評価も必要です。pubmed-stream でできることとできないことをご覧ください。

重要な論文が見つからないことがあるのはなぜですか？ 全文は PMC からのみ取得され、検索結果は新しいものから順に返されます。残りの論文については abstracts が PubMed の抄録を保存します。また、古い論文や購読限定の論文も、重要な論文の周辺情報を通じて、スタブとして、または引用元の論文からのリンクとして、ナレッジグラフに加わります。

Obsidian は必要ですか？ ナレッジグラフを視覚的に探索する場合にのみ必要です。ノートはプレーンな Markdown で、チュートリアル 5 では Python での分析方法を紹介しています。

商用利用できますか？ はい。NCBI の利用ポリシーを遵守すれば、MIT ライセンスのもとで利用できます。

引用、謝辞、ライセンス

pubmed-stream は、University of Massachusetts の生物医学研究を支援するため、Haran Lab、Bucci Lab、Microbiology & Microbiome Dynamics AI HUB によって開発されました。E-utilities と PubMed Central へのオープンアクセスを提供している NCBI に感謝します。研究で使用する場合は、引用をお願いします。GitHub のリポジトリのメインページにある Cite this repository ボタンから、CITATION.cff に基づく APA 形式と BibTeX 形式の引用情報を取得できます。

@software{pubmed_stream_2026,
  title = {pubmed-stream: From PubMed Searches to Knowledge Graphs of the Biomedical Literature},
  author = {Haran Lab and Bucci Lab and Microbiology \& Microbiome Dynamics AI HUB},
  organization = {University of Massachusetts},
  year = {2026},
  url = {https://github.com/melhzy/pubmed-stream},
  note = {Built on NCBI E-utilities}
}

pubmed-stream は、MIT License のもとで提供されるフリーソフトウェアです。各バージョンでの変更点は変更履歴に記載されています。

質問やバグ報告：issue を作成。パッケージ：pypi.org/project/pubmed-stream。