PyEuropePMC

PyEuropePMC

PyEuropePMC 是一个用于 Europe PMC 的 Python 客户端。它可以检索文献、下载开放获取全文，并将 JATS XML 解析为元数据、纯文本和结构化章节。它还提供命令行工具和供 AI Agent 使用的 MCP 服务。

✨ 功能

• Europe PMC 搜索：支持普通查询或流式 QueryBuilder，提供分页，并可将结果导出为 JSON、XML 或 Dublin Core 格式。搜索指南
• 一次搜索另外十个来源，并合并重复结果：PubMed、arXiv、ClinicalTrials.gov、OpenAlex、Semantic Scholar、CORE、DBLP、DOAJ、HAL 和 Zenodo。Semantic Scholar 需要 semanticscholar extra，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	Installs	Adds
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	大模型分析、大模型 MCP 工具和 pyeuropepmc claim
ui	flask, tornado	Web UI（pyeuropepmc claim serve）
signing	cryptography	系统综述的已签名搜索日志
benchmark	huggingface-hub	下载已发布的基准数据集（pyeuropepmc benchmark download）
rdf	nothing	保留此项以确保现有安装继续正常工作；核心 rdflib 可自行写入 JSON-LD
standard	jupyterlab, notebook, ipykernel, ipython, ipywidgets, matplotlib, seaborn, pandas, numpy, tabulate, xlsxwriter, requests-cache, rich	Jupyter 以及分析、绘图和导出软件包
all	all of the above	所有可选功能

从 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。每个块都有一个 type，例如 paragraph、list、table 或 figure。表格和图都有 label 和 caption，表格还包含 rows。XML 解析指南介绍了其他提取器。

🔒 安全的 XML 解析

PyEuropePMC 使用 defusedxml 解析读取的每个 XML 文档：包括全文文章、Europe PMC 搜索结果、arXiv 和 PubMed 响应，以及本地文件。文档可以包含 DOCTYPE 声明，但如果声明了内部或外部实体，则会被拒绝，而不会进行展开；FullTextXMLParser 会引发 ParsingError。项目不使用 lxml，也无需安装它。

💻 命令行

Command	What it does
pyeuropepmc unified_search	使用去重功能对多个来源进行 search，或使用 compare-sources 查看各来源的结果
pyeuropepmc normalize	将 JATS XML 转换为纯文本（text）、章节（sections）或 BioC JSON（bioc）；使用 classify 对标题分类；使用 batch 处理目录
pyeuropepmc benchmark	在本地文件夹或已发布的数据集上为 XML 解析器评分并分析其性能
pyeuropepmc claim	使用大模型 Agent 对照 Europe PMC 文献检查文本中的论断（需要 agentic 额外依赖和 API 密钥）

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

除非传入 --source，否则 unified_search search 会查询 Europe PMC、PubMed 和 arXiv。对任何命令添加 --help 可查看其选项。

🤖 MCP 服务

pyeuropepmc-mcp 通过 Model Context Protocol 提供 47 个工具，让 AI Agent 能够搜索文献、阅读论文并导出参考文献。该服务包含在核心安装包中。

任务	工具的功能
搜索	搜索 Europe PMC 和另外十个来源，合并重复结果并提供命中数、作者搜索和 ClinicalTrials.gov 搜索
汇总搜索结果	统计 Europe PMC 对整个结果集计算的逐年论文数、引用阈值和开放获取占比；根据首批记录统计期刊、作者、出版类型、国家、资助方和引用数据；每项均标注为 exact 或 sample，且不返回记录
检查查询	检查 Europe PMC 会默默接受的错误（它会改为执行另一个查询，而不是报错）；提供查询构建器、PubMed 转换器，以及与已知论文进行召回率检查的功能
规划搜索	将研究问题拆分为 PICO、PICOS、PICOT 或 SPIDER 要素（原文照录，报告缺失项，绝不臆造），并生成经过检查的查询；还可为搜索词提供 MeSH 标题、树编号和入口词，离线使用捆绑快照，或按需从 NLM 获取
查找论文	单次调用即可根据 PMID、PMCID 或 DOI 获取最多 100 篇论文的元数据；还可通过 Europe PMC、Crossref、OpenAlex、Semantic Scholar 和 iCite 为单篇论文补充引用影响、资助方、机构、开放获取状态和撤稿信息
阅读	以 Markdown 或带类型的章节形式读取开放获取全文，可筛选章节并限制大小；也可读取按背景、方法、结果、局限性等类别标记的句子，无论章节标题如何命名；还可获取图、表、补充文件，以及通过 Unpaywall 查找其他论文的免费副本
实体和数据	从论文中通过文本挖掘提取基因、化学物质和疾病；查找提及某个实体的论文，以及论文链接的数据（登录号、BioStudies、模式生物数据库）
引用	查找引用论文、参考文献并遍历引用图
导出	将搜索结果或论文列表导出为 BibTeX、RIS、CSL-JSON、CSV、JSON 或 Markdown
资源和提示词	提供 epmc://paper/{pmcid}（全文）、可附加的 /references 和 /outline 资源，以及用于文献综述、批判性评价和引用追踪的即用型工作流
诊断	服务状态探测和缓存控制
本地和大模型工具	本地全文索引、参考文献转换和由大模型驱动的分析

pip install "pyeuropepmc[all]" 可启用所有工具；否则，bib_* 工具需要 bibliography，大模型工具需要 agentic 和兼容 OpenAI 的 API 密钥（请参阅下方的配置）。

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，只需一条命令即可添加：

claude mcp add pyeuropepmc -- uvx pyeuropepmc mcp

Cursor（.cursor/mcp.json）和 VS Code（.vscode/mcp.json，使用 "servers" 而非 "mcpServers"）采用相同的 command 和 args。

HTTP 传输默认开放，除非设置 bearer token（PYEUROPEPMC_MCP_AUTH_TOKEN 或 --auth-token-file；运行 pyeuropepmc-mcp --generate-token 可生成 token）。因此，请将其限制在 127.0.0.1 上、设置 token，或在前面部署带身份验证的代理；如果代理会转发其公共主机名，请添加 --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；模型默认使用 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 · 操作数：0.59/s · 运行次数：30
get_citations	1.789s	0.318s	0.0MB	❌	31	0
p50：1.666s · p95：2.851s · 操作数：0.56/s · 运行次数：30

ArticleClient_Cached

方法	平均耗时	标准差	平均内存	缓存	请求数	错误数
get_article_details	<1ms	<1ms	0.0MB	✅	1	0
p50：17µs · p95：29µs · 操作数：53390.19/s · 运行次数：30
get_citations	<1ms	<1ms	0.0MB	✅	1	0
p50：19µs · p95：30µs · 操作数：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 · 运行次数：30
get_hit_count	2.085s	0.562s	0.0MB	❌	31	0
p50：1.933s · p95：3.668s · ops：0.48/s · 运行次数：30

SearchClient_Cached

方法	平均耗时	标准差	平均内存	缓存	请求数	错误数
search	<1ms	<1ms	0.0MB	✅	1	0
p50：109µs · p95：134µs · ops：8795.90/s · 运行次数：30
get_hit_count	<1ms	<1ms	0.0MB	✅	1	0
p50：111µs · p95：137µs · ops：8603.62/s · 运行次数：30

FullTextClient_NoCache

方法	平均耗时	标准差	平均内存	缓存	请求数	错误数
check_fulltext_availability	1.050s	0.148s	0.1MB	❌	93	0
p50：0.998s · p95：1.388s · ops：0.95/s · 运行次数：30

FullTextClient_Cached

方法	平均耗时	标准差	平均内存	缓存	请求数	错误数
check_fulltext_availability	<1ms	<1ms	0.0MB	✅	3	0
p50：20µs · p95：21µs · ops：48496.45/s · 运行次数：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 中读取许可证信息。