PyEuropePMC

PyEuropePMC

PyEuropePMC は、Europe PMC 用の Python クライアントです。文献を検索し、オープンアクセスの全文をダウンロードして、JATS XML をメタデータ、プレーンテキスト、構造化されたセクションに解析します。また、コマンドラインツールと、AI エージェント向けの MCP サーバーも提供します。

✨ 特長

• Europe PMC 検索：プレーンなクエリまたは柔軟な QueryBuilder を使った検索、ページネーション、JSON、XML、Dublin Core 形式での結果取得に対応しています。検索ガイド
• 1 回の検索でさらに 10 のソースを検索し、重複を統合します：PubMed、arXiv、ClinicalTrials.gov、OpenAlex、Semantic Scholar、CORE、DBLP、DOAJ、HAL、Zenodo。Semantic Scholar には semanticscholar エクストラが、CORE には API キーが必要です。複数ソース検索
• 全文：XML（最初に Europe PMC を検索し、次にほかのオープンソースを検索）、PDF、HTML に対応し、Europe PMC FTP サイトからの PDF 一括ダウンロードも可能です。全文の取得
• JATS XML の解析：メタデータ、著者、表、図、参考文献に対応し、プレーンテキストと Markdown を出力します。また、検索拡張生成（RAG）用の型付きセクション、JATS の正規化、BioC へのエクスポートも可能です。XML の解析、JATS の正規化
• 遺伝子、疾患、化学物質およびそれらの関係に関するテキストマイニング注釈。例
• 引用情報とメタデータ：引用グラフをたどり、Crossref、Unpaywall、OpenAlex、Semantic Scholar、DataCite、ORCID、ROR、iCite の情報でレコードを補完します。引用の追跡、情報の補完
• 分析：pandas の DataFrame、引用統計、重複検出、プロット、システマティックレビュー用の PRISMA 形式の検索ログに対応しています。分析、レビューの追跡
• 解析済み論文からの RDF ナレッジグラフ：パッケージに同梱されている rdf_map.yml によってマッピングされます。独自の設定を使うには、RDFMapper(config_path=...) または PipelineConfig(rdf_config_path=...) を渡してください。データモデルと RDF
• コマンドラインと MCP サーバーについては、以下で説明します。

📦 インストール

pip install pyeuropepmc                              # core
pip install "pyeuropepmc[analytics,visualization]"   # add extras (quote the brackets)
pip install "pyeuropepmc[all]"                       # every optional feature

PyEuropePMC は Python 3.10〜3.13 に対応しています。コアのインストールには、検索、全文ダウンロード、XML 解析、RDF、コマンドライン、MCP サーバーが含まれます。追加機能をインストールすると、次の機能が追加されます。

Extra	インストールされるもの	追加される機能
analytics	pandas, numpy	to_dataframe、citation_statistics、quality_metrics、remove_duplicates、CSV エクスポート
visualization	matplotlib, seaborn, pandas, numpy	plot_* 関数と create_summary_dashboard
export	pandas, tabulate, xlsxwriter	Excel および Markdown テーブルへのエクスポート（pyeuropepmc.utils.export）
semanticscholar	semanticscholar	SemanticScholarClient と semantic_scholar 検索ソース
enrichment	semanticscholar	PaperEnricher での Semantic Scholar データ
bibliography	bibtexparser	BibTeX の解析、検証、RIS/CSL 変換（bib_* MCP ツールを含む）
zotero	pyzotero	Zotero クライアント
agentic	openai, langchain, langchain-openai, langgraph, jinja2	LLM 分析、LLM MCP ツール、pyeuropepmc claim
ui	flask, tornado	Web UI（pyeuropepmc claim serve）
signing	cryptography	システマティックレビュー用の署名付き検索ログ
benchmark	huggingface-hub	公開済みベンチマークデータセットのダウンロード（pyeuropepmc benchmark download）
rdf	なし	既存のインストールとの互換性を保つために残されています。コアの rdflib が JSON-LD を直接書き出します
standard	jupyterlab, notebook, ipykernel, ipython, ipywidgets, matplotlib, seaborn, pandas, numpy, tabulate, xlsxwriter, requests-cache, rich	Jupyter と、分析、プロット、エクスポート用のパッケージ
all	上記すべて	すべてのオプション機能

1.x からアップグレードしますか？移行ガイドに、追加機能として分離された機能が記載されています。

🚀 クイックスタート

from pyeuropepmc import FullTextClient, FullTextXMLParser, QueryBuilder, SearchClient

# 1. Search Europe PMC for open-access articles ("CRISPR AND OPEN_ACCESS:y")
query = QueryBuilder().keyword("CRISPR").and_().field("open_access", True).build()
with SearchClient() as search:
    hits = search.search_and_parse(query, pageSize=10)
pmcid = next(hit["pmcid"] for hit in hits if hit.get("pmcid"))

# 2. Download the article's JATS XML (raises an error if no source has it)
with FullTextClient() as fulltext:
    xml_path = fulltext.download_xml_by_pmcid(pmcid, output_path=f"articles/{pmcid}.xml")

# 3. Parse it
parser = FullTextXMLParser(xml_path.read_text(encoding="utf-8"))
metadata = parser.extract_metadata()
print(metadata["title"])
print(", ".join(metadata["authors"][:3]))
text = parser.to_plaintext()  # or parser.to_markdown()

# 4. Collect text blocks with their section path, ready to chunk and embed for RAG
chunks = []
for section in parser.get_full_text_sections_structured():
    if section["section_type"] not in ("front", "body"):  # skip back matter and appendices
        continue
    for block in section["content"]:
        if block.get("text"):
            path = section.get("section_path", section["title"])
            chunks.append({"section": path, "type": block["type"], "text": block["text"]})
print(f"{len(chunks)} text blocks")

section_type は、タイトルと要約には front、その後は body、back、または appendix です。各ブロックには、paragraph、list、table、figure などの type があります。表と図には label と caption があり、表にはさらに rows があります。XML 解析ガイドでは、その他の抽出機能について説明しています。

🔒 安全な XML 解析

PyEuropePMC は、読み込むすべての XML ドキュメントを defusedxml で解析します。対象には、全文記事、Europe PMC の検索結果、arXiv と PubMed のレスポンス、ローカルファイルが含まれます。DOCTYPE 宣言は受け入れられますが、内部または外部エンティティを宣言するドキュメントは展開せずに拒否され、FullTextXMLParser は ParsingError を送出します。lxml は使用しておらず、インストールする必要もありません。

💻 コマンドライン

コマンド	機能
pyeuropepmc unified_search	複数のソースを重複排除して search するか、compare-sources で各ソースの結果を確認します
pyeuropepmc normalize	JATS XML をクリーンなテキスト（text）、セクション（sections）、または BioC JSON（bioc）に変換します。見出しを classify したり、ディレクトリを batch 処理したりできます
pyeuropepmc benchmark	ローカルフォルダーまたは公開済みデータセットで XML パーサーのスコアを算出し、プロファイルします
pyeuropepmc claim	LLM エージェントを使って、テキスト内の主張を Europe PMC の文献と照合します（agentic 追加機能と API キーが必要です）

pyeuropepmc unified_search search "CRISPR base editing" --limit 10 --output results.json
pyeuropepmc benchmark list-datasets

unified_search search は、--source を指定しない限り、Europe PMC、PubMed、arXiv を検索します。各コマンドに --help を追加すると、オプションを確認できます。

🤖 MCP サーバー

pyeuropepmc-mcp は Model Context Protocol を通じて47個のツールを提供するため、AI エージェントは文献を検索し、論文を読み、参考文献をエクスポートできます。サーバーはコアインストールに含まれています。

ジョブ	ツールの機能
検索	Europe PMC とその他10のソースを対象に、重複を統合した検索、ヒット件数、著者検索、ClinicalTrials.gov を利用できます
検索結果の要約	結果全体を対象に Europe PMC が集計した年別論文数、被引用数のしきい値、オープンアクセスの割合に加え、最初のレコードから取得したジャーナル、著者、出版物の種類、国、資金提供者、被引用統計を確認できます。各項目には exact または sample のラベルが付き、レコード自体は返されません
クエリの確認	エラーではなく別のクエリに対する結果を返すため、Europe PMC が黙って受け入れてしまう間違いを検出するリンター、クエリビルダー、PubMed トランスレーター、既知の論文との再現率チェックを利用できます
検索の計画	研究上の問いを PICO、PICOS、PICOT、SPIDER の各要素に分割します（原文どおりに示し、欠けている要素を報告し、要素を創作することはありません）。検証済みのクエリも作成できます。また、検索語に対応する MeSH 見出し、ツリー番号、エントリータームを、同梱のスナップショットからオフラインで、またはリクエストに応じて NLM から取得できます
論文の検索	1回の呼び出しで PMID、PMCID、DOI を指定して最大100件の論文のメタデータを取得できます。さらに、Europe PMC、Crossref、OpenAlex、Semantic Scholar、iCite から、被引用インパクト、資金提供者、機関、オープンアクセス状況、撤回情報を取得して1件の論文を補完できます
閲覧	オープンアクセスの全文を Markdown または型付きセクションとして取得できます。セクションフィルターとサイズ上限を指定でき、見出しの名前にかかわらず、背景、方法、結果、限界などのラベルが付いた文として取得することもできます。図、表、補足ファイルのほか、Unpaywall を通じて他の論文の無料コピーも利用できます
エンティティとデータ	論文からテキストマイニングで抽出した遺伝子、化学物質、疾患、エンティティに言及する論文、論文がリンクするデータ（アクセッション番号、BioStudies、モデル生物データベース）を利用できます
引用	被引用論文、参考文献、引用グラフのたどり歩きを利用できます
エクスポート	検索結果または論文リストを BibTeX、RIS、CSL-JSON、CSV、JSON、Markdown 形式でエクスポートできます
リソースとプロンプト	epmc://paper/{pmcid}（全文）、添付可能なリソースとしての /references と /outline、文献レビュー、批判的評価、引用の追跡にすぐ使えるワークフローを利用できます
診断	サービス状態の確認とキャッシュ制御を利用できます
ローカルおよび LLM ツール	ローカル全文インデックス、参考文献の変換、LLM を活用した分析を利用できます

pip install "pyeuropepmc[all]" を実行するとすべてのツールが有効になります。それ以外の場合、bib_* ツールには bibliography が必要で、LLM ツールには agentic と OpenAI 互換の API キーが必要です（下記の「Configuration」を参照）。

pyeuropepmc-mcp                                # stdio, for Claude Desktop and similar clients
pyeuropepmc mcp                                # the same server, through the CLI
pyeuropepmc-mcp --transport streamable-http    # HTTP at http://127.0.0.1:8000/mcp

Claude Desktop など、サーバーを自分で起動するクライアントの場合：

{
  "mcpServers": {
    "pyeuropepmc": {
      "command": "pyeuropepmc-mcp"
    }
  }
}

インストールせずに使う場合は、"command": "uvx" と "args": ["pyeuropepmc", "mcp"] を指定しても同じです。これは MCP Registry のエントリーがクライアントに実行を指示する内容です。Claude Code では、1つのコマンドで追加できます：

claude mcp add pyeuropepmc -- uvx pyeuropepmc mcp

Cursor（.cursor/mcp.json）と VS Code（.vscode/mcp.json。"mcpServers" の代わりに "servers" の下に記述）でも、同じ command と args を使用します。

HTTP トランスポートは、ベアラートークン（PYEUROPEPMC_MCP_AUTH_TOKEN または --auth-token-file）を設定しない限り認証なしで利用できます（pyeuropepmc-mcp --generate-token でトークンを生成できます）。そのため、127.0.0.1 でのみ公開するか、トークンを設定するか、認証プロキシの背後に配置してください。公開ホスト名を転送するプロキシの背後で使用する場合は、--allowed-host mcp.example.org を追加してください。MCP サーバーガイドでは一般的なワークフローを説明し、ツールリファレンスではすべてのツールを一覧表示しています。このサーバーは、MCP Registry に io.github.JonasHeinickeBio/pyeuropepmc として登録されています。

⚙️ 設定

Europe PMC では API キーは不要です。それ以外のサービスでは、これらの環境変数を読み込みます。FullTextClient(email=...) や EnrichmentConfig(unpaywall_email=...) のようにコードで渡した値が優先されます。

変数	用途
UNPAYWALL_EMAIL, CROSSREF_EMAIL	Unpaywall と Crossref の連絡先メールアドレスです。FullTextClient の Unpaywall フォールバックには、どちらか一方が必要です。MCP ツール find_open_access でも同様です。
OPENALEX_EMAIL, DATACITE_EMAIL, ROR_EMAIL, ROR_CLIENT_ID	その他のエンリッチメントソース
SEMANTIC_SCHOLAR_API_KEY	Semantic Scholar。より高いレート制限が適用されます。
CORE_API_KEY	core 検索ソース
OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL	OpenAI 互換 API での LLM 機能。モデルのデフォルトは gpt-4o-mini です。
ZOTERO_API_KEY, ZOTERO_LIBRARY_ID, ZOTERO_LOCAL	Zotero クライアント
PYEUROPEPMC_MCP_TRANSPORT, PYEUROPEPMC_MCP_HOST, PYEUROPEPMC_MCP_PORT, PYEUROPEPMC_MCP_LOG_LEVEL	pyeuropepmc-mcp オプションのデフォルト値

pyeuropepmc コマンドは、カレントディレクトリ、その親ディレクトリのいずれか、または ~/.config/pyeuropepmc/ にある最初の .env ファイルも読み込みます。すでに設定されている変数の値はそのまま保持されます。

📚 ドキュメント

ガイドは docs/ にあります。インストールとクイックスタートから始めるか、API リファレンス、キャッシュ、サンプルスクリプト、変更履歴を直接ご覧ください。

パーサーのベンチマーク。 benchmark_xmls/xml にある 55 件の JATS 論文で、パーサーの平均複合品質スコアは 0.998 です（2026-09-15 に測定）。ベンチマークガイドでは、指標について説明しています。ソースをチェックアウトした状態からスコアを再現する場合、または公開済みのデータセットを採点する場合は、次の手順に従ってください。

pyeuropepmc benchmark run local --local-path benchmark_xmls/xml --limit 55
pyeuropepmc benchmark download PLOS_1000   # 1,000 articles, 1.3 GB
pyeuropepmc benchmark run PLOS_1000

週次のベンチマークワークフローでは、API クライアントの処理時間を計測し、以下のセクションを更新するプルリクエストを作成します。

📊 パフォーマンス

最終更新：2026-09-14

指標	値
ベンチマーク対象のメソッド	10
リクエスト総数	224
平均呼び出し時間	0.871s
成功率	100.0%

📈 ベンチマークレポート全体を表示

🚀 pyEuropePMC ベンチマークスイート

生成日時： 2026-09-14 07:45:39

📊 概要

• ベンチマーク総数： 6
• メソッド総数： 10
• 成功した実行： 10
• 失敗した実行： 0
• キャッシュ有効： 5

ArticleClient_NoCache

メソッド	平均時間	標準偏差	平均メモリ	キャッシュ	リクエスト	エラー
get_article_details	1.707s	0.212s	0.0MB	❌	31	0
p50: 1.620s · p95: 2.235s · ops: 0.59/s · 実行回数: 30
get_citations	1.789s	0.318s	0.0MB	❌	31	0
p50: 1.666s · p95: 2.851s · ops: 0.56/s · 実行回数: 30

ArticleClient_Cached

メソッド	平均時間	標準偏差	平均メモリ	キャッシュ	リクエスト	エラー
get_article_details	<1ms	<1ms	0.0MB	✅	1	0
p50: 17µs · p95: 29µs · ops: 53390.19/s · 実行回数: 30
get_citations	<1ms	<1ms	0.0MB	✅	1	0
p50: 19µs · p95: 30µs · ops: 48437.33/s · 実行回数: 30

## SearchClient_NoCache

メソッド	平均時間	標準偏差	平均メモリ	キャッシュ	リクエスト数	エラー数
search	2.074s	0.262s	0.1MB	❌	31	0
p50: 1.964s · p95: 2.673s · ops: 0.48/s · runs: 30
get_hit_count	2.085s	0.562s	0.0MB	❌	31	0
p50: 1.933s · p95: 3.668s · ops: 0.48/s · runs: 30

SearchClient_Cached

メソッド	平均時間	標準偏差	平均メモリ	キャッシュ	リクエスト数	エラー数
search	<1ms	<1ms	0.0MB	✅	1	0
p50: 109µs · p95: 134µs · ops: 8795.90/s · runs: 30
get_hit_count	<1ms	<1ms	0.0MB	✅	1	0
p50: 111µs · p95: 137µs · ops: 8603.62/s · runs: 30

FullTextClient_NoCache

メソッド	平均時間	標準偏差	平均メモリ	キャッシュ	リクエスト数	エラー数
check_fulltext_availability	1.050s	0.148s	0.1MB	❌	93	0
p50: 0.998s · p95: 1.388s · ops: 0.95/s · runs: 30

FullTextClient_Cached

メソッド	平均時間	標準偏差	平均メモリ	キャッシュ	リクエスト数	エラー数
check_fulltext_availability	<1ms	<1ms	0.0MB	✅	3	0
p50: 20µs · p95: 21µs · ops: 48496.45/s · runs: 30

🔁 キャッシュありとキャッシュなしの比較

ArticleClient — キャッシュありとキャッシュなし

メソッド	キャッシュなしの平均	キャッシュありの平均	高速化率（なし／あり）
get_article_details	1.707s	<1ms	>17074.4x
get_citations	1.789s	<1ms	>17888.5x

FullTextClient — キャッシュありとキャッシュなし

メソッド	キャッシュなしの平均	キャッシュありの平均	高速化率（なし／あり）
check_fulltext_availability	1.050s	<1ms	>10504.7x

SearchClient — キャッシュありとキャッシュなし

メソッド	キャッシュなしの平均	キャッシュありの平均	高速化率（なし／あり）
get_hit_count	2.085s	<1ms	17941.89x
search	2.074s	<1ms	18245.92x

• SearchClient の平均高速化率（キャッシュなし／あり）： 18093.91x

---

注：平均値は測定した反復処理の結果から算出しています。「-」はデータがないことを示します。「<1ms」のような値は、キャッシュによる応答が非常に高速であることを示します。キャッシュありの時間が正確に測定できないほど小さい場合、高速化率は下限値として表示されます。

⚙️ 再現方法

モジュール式ベンチマークをローカルで実行し、これらの成果物を再生成します。

pytest tests/benchmark_article_client.py::test_modular_benchmark_system -m benchmark --force-enable-socket --timeout=3600

• 詳細な JSON 結果：MODULAR_BENCHMARK_RESULTS.json

🤝 コントリビューション

コントリビューションを歓迎します。開発ガイドでは、セットアップ、テスト、コード品質、リリースプロセスについて説明しています。バグの報告や機能の提案は、イシュートラッカーからお寄せください。

📝 引用

PyEuropePMC が研究に役立った場合は、引用し、使用したバージョンを記載してください（pip show pyeuropepmc で確認できます）。

@software{pyeuropepmc,
  author = {Heinicke, Jonas},
  title  = {{PyEuropePMC}: a Python toolkit for Europe PMC},
  url    = {https://github.com/JonasHeinickeBio/pyEuropePMC}
}

文献データは Europe PMC に由来します。データソースとして明記してください。

📄 ライセンス

PyEuropePMC は MIT License の下で公開されています。取得した記事にはそれぞれ独自のライセンスが適用されており、FullTextXMLParser.extract_license() は XML からライセンスを読み取ります。