io.github.JonasHeinickeBioPublished by GitHub account JonasHeinickeBiov4.7.1Updated Nov 7, 2026
Europe PMC search, search analytics, full text, enrichment, PICO, MeSH, data links, export, auth
Searches biomedical and scientific literature across Europe PMC and other sources, reads open-access full text, and exports references for an AI assistant.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
[PyPI version] [Python versions] [CI] [codecov] [License: MIT] [MCP server]
PyEuropePMC is a Python client for Europe PMC. It searches the literature, downloads open-access full text, and parses JATS XML into metadata, plain text and structured sections. It also ships a command-line tool and an MCP server for AI agents.
QueryBuilder, pagination, and results as JSON, XML or Dublin Core. Search guidesemanticscholar extra and CORE an API key. Multi-source searchrdf_map.yml that ships with the package; pass RDFMapper(config_path=...) or PipelineConfig(rdf_config_path=...) to use your own. Data models and RDFPyEuropePMC supports Python 3.10 to 3.13. The core install covers search, full-text download, XML parsing, RDF, the command line and the MCP server. The extras add:
Upgrading from 1.x? The migration guide lists what moved into extras.
section_type is front for the title and abstract, then body, back or appendix. Each block has a type such as paragraph, list, table or figure. Tables and figures carry label and caption, and tables also carry rows. The XML parsing guide covers the other extractors.
PyEuropePMC parses every XML document it reads with defusedxml: full-text articles, Europe PMC search results, arXiv and PubMed responses, and local files. A DOCTYPE declaration is accepted, but a document that declares entities, internal or external, is refused rather than expanded; FullTextXMLParser raises ParsingError. lxml is not used and does not need to be installed.
unified_search search queries Europe PMC, PubMed and arXiv unless you pass --source. Add --help to any command for its options.
pyeuropepmc-mcp serves 48 tools over the Model Context Protocol, so an AI agent can search the literature, read papers and export references. The server is part of the core install.
pip install "pyeuropepmc[all]" enables every tool; otherwise the bib_* tools need bibliography, and the LLM tools need agentic plus an OpenAI-compatible API key (see Configuration below).
For Claude Desktop and other clients that start the server themselves:
Without an install, "command": "uvx" with "args": ["pyeuropepmc", "mcp"] does the same; this is what the MCP Registry entry tells clients to run. For Claude Code, one command adds it:
Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json, under "servers" instead of "mcpServers") take the same command and args.
The HTTP transport is open unless you set a bearer token (PYEUROPEPMC_MCP_AUTH_TOKEN or --auth-token-file; pyeuropepmc-mcp --generate-token makes one), so keep it on 127.0.0.1, set a token, or put an authenticating proxy in front of it; behind a proxy that forwards its public host name, add --allowed-host mcp.example.org. The MCP server guide walks through the common workflows, and the tool reference lists every tool. The server is listed in the MCP Registry as io.github.JonasHeinickeBio/pyeuropepmc.
Europe PMC needs no API key. Other services read these environment variables. A value passed in code, such as FullTextClient(email=...) or EnrichmentConfig(unpaywall_email=...), takes precedence.
The pyeuropepmc command also loads the first .env file it finds in the current directory, one of its parents, or ~/.config/pyeuropepmc/. Variables that are already set keep their values.
The guides are in docs/. Start with installation and the quick start, or go straight to the API reference, caching, the example scripts and the changelog.
Parser benchmark. On the 55 JATS articles in benchmark_xmls/xml, the parser's mean composite quality score is 0.998 (measured on 2026-09-15). The benchmarking guide explains the metrics. To reproduce the score from a source checkout, or to score a published dataset:
The weekly benchmark workflow times the API clients and opens a pull request that refreshes the section below.
Last updated: 2026-09-14
Generated: 2026-09-14 07:45:39
Notes: Means are computed over measured iterations; '-' indicates missing data. Values like '<1ms' indicate very fast cached responses. Speedups shown as lower-bounds when cached times are too small to measure precisely.
Run the modular benchmark locally and regenerate these artifacts:
MODULAR_BENCHMARK_RESULTS.jsonContributions are welcome. The development guide covers setup, testing, code quality and the release process. Report bugs and suggest features in the issue tracker.
If PyEuropePMC supports your research, please cite it and give the version you used (pip show pyeuropepmc prints it):
The literature itself comes from Europe PMC; please acknowledge it as your data source.
PyEuropePMC is released under the MIT License. Articles you retrieve keep their own licences, which FullTextXMLParser.extract_license() reads from the XML.
Source: README.md at commit 034b655
Unified literature search
Search across multiple literature sources (PubMed, arXiv, Semantic Scholar, OpenAlex, ClinicalTrials.gov) in parallel, with automatic cross-source deduplication. A source that fails does not fail the call; set `diagnostics` to see which one did and why, and to tell an empty source from an unavailable one.
limitqueryrequiredsourcesdiagnostics[Legacy] Search Europe PMC
Search Europe PMC for papers (single source — prefer `unified_search` for multi-source coverage). At most ``limit`` records are fetched; optional filters narrow the query by date, open access, full text availability and source.
sortlimitqueryrequiredsourcedate_tosynonymdate_fromopen_accessresult_typehas_fulltextCount papers
Number of Europe PMC records matching a query, without fetching them. Use it to size a search before choosing ``limit`` for `search_papers`.
queryrequiredsourcedate_tosynonymdate_fromopen_accesshas_fulltextGet paper details
Get detailed paper information by PMID, PMCID, or DOI (Europe PMC).
doipmidpmcidSearch authors
Search for authors in Europe PMC.
limitqueryrequiredGet paper citations
Get papers that cite a given paper (Europe PMC).
pmidrequiredlimitsourceGet paper references
Get the reference list of a paper (backward citations, Europe PMC).
limitsourcearticle_idrequiredCitation snowball walk
Walk the citation graph forward (cited-by), backward (references), or both, with configurable depth and a minimum-citation-count filter.
strategymax_depthidentifierrequiredmax_papersmin_citationsSearch ClinicalTrials.gov
Search ClinicalTrials.gov for studies by condition, intervention, or free-text query.
limitquerystatusconditioninterventionQuery local full-text index
Search the local SQLite FTS5 full-text index for papers whose full text matches a query. A fresh index handle is opened per call rather than cached: SQLite connections are only safe to use from the thread that created them, and each call may run on a different worker thread.
limitqueryrequiredindex_pathGet paper full text
Fetch the structured full text of an open-access paper from Europe PMC. Returns metadata, the list of available section titles, and the content in the requested format. When the content is longer than ``max_chars`` it is cut at a block boundary and ``truncated`` is true: ask again with ``sections`` for the part you need. Only open-access articles have full text; anything else fails with the reason.
doipmidpmcidformatsectionsmax_charsinclude_referencesExtract paper figures
Extract figures, tables and supplementary files from a PMC Open Access article. Each item carries its label, caption and the Europe PMC URL its file can be downloaded from. A figure supplement also names the figure it belongs to.
doipmidpmcidinclude_tablesinclude_supplementsTag paper sentences by role
The sentences of an open-access paper's body, grouped by what they do: background, motivation, method, result, claim (the authors' interpretation), limitation, conclusion. Front matter, the reference list and administrative sections (acknowledgments, funding, conflicts) are left out. Rule-based and offline apart from the download: the section a sentence is in sets its default role and cues in the sentence correct it. Where no rule is sure the sentence is `unknown` instead of a guess; in a paper without recognisable headings only background, method and conclusion sentences are recognised. Measured precision per role is in the guide; discussion sections are the hardest part. Sentences come in reading order and are never cut: `truncated` says whether some were left out. Use it to pull the methods or the results of a paper without knowing what its sections are called.
doipmidpmcidrolesuse_llmsectionsmax_charsmin_confidenceEurope PMC service status
Is Europe PMC up right now? Probes the endpoints this server depends on (search, full text, citations, annotations) and returns ok, degraded (some fail), down (none answers) or unknown (only 4xx answers: a blocked probe or a moved endpoint), with the HTTP status and the time in milliseconds of each. Use it before retrying a tool that failed with a network error, a timeout or a 5xx. The answer is kept for 30 seconds, so asking again does not probe again (`cached` says so), and it contains no URLs or response bodies.
Takes no parameters.
Cache status
How full are the server's caches and how often do they help? For the search, article and annotation clients and for the full-text XML cache: entries, capacity, size, hits, misses and hit rate. Counts only: no cache keys (they can contain query text), no cached content and no file paths.
Takes no parameters.
Clear a server cache
Empty one of the server's in-memory caches, so that the next call asks Europe PMC again. Only worth doing when you suspect a cached answer is stale (the caches hold results for a day); every cleared entry has to be fetched again, which is load on Europe PMC. It changes server state, so a client may ask for approval. It never touches files on disk.
scoperequiredValidate a Europe PMC query
Check a Europe PMC query before running it. Europe PMC does not reject a malformed query, it answers a different one: an unclosed parenthesis or a dangling operator is dropped silently, an unknown field, a flag that is not y/n and a date range with a missing or reversed bound match nothing, and AND mixed with OR without parentheses is not read as either grouping. Each problem comes with its position. `valid` is false when there are errors; warnings are things worth a second look. `normalized` is the cleaned-up query (capital operators, explicit AND) and is only given for a query without errors.
queryrequiredBuild a Europe PMC query
Build a Europe PMC query from structured input instead of writing syntax by hand, and check the result. Returns the query, a plain-language explanation of what it asks for, and any warnings. At least one of all_of, any_of or a filter is needed (none_of alone would match almost everything). The same filters are available on `search_papers`.
citesall_ofany_ofsourcedate_tonone_ofdate_fromopen_accesshas_fulltextTranslate a Europe PMC query
Rewrite a Europe PMC query for another database. For PubMed the field codes map where they have an equivalent (TITLE[ti], AUTH[au], JOURNAL[ta], dates[dp], ...); a construct that does not map (CITES, HAS_*, CITED, ...) is left out and named in `warnings` and `dropped`, and `exact` is false whenever the translation is narrower, broader or only approximate. The other targets search free text, so field codes and operators are stripped and `exact` is always false. A query with errors is refused; see `validate_query`.
queryrequiredtargetEvaluate a query against known papers
Score a Europe PMC query against papers you already know, for systematic-review work: recall (how many of the included PMIDs it finds) and how many excluded ones it still finds, with the PMIDs it misses. This runs the query on Europe PMC itself, so it measures what the search really returns, not a local reading of the syntax. PMIDs that Europe PMC does not know are reported apart and left out of the scores. A query with errors is refused; see `validate_query`.
queryrequiredexcluded_pmidsincluded_pmidsrequiredExport papers
Export papers as a file's worth of text to hand to a reference manager or a spreadsheet: BibTeX, RIS or CSL-JSON (Zotero, Mendeley, EndNote, Pandoc) or CSV, JSON or Markdown. Give a search `query` or a list of `ids`. BibTeX keys look like `vasiliou2005analysis`, are unique within the export and do not change when it is cut to size; text that LaTeX reads as syntax (& % # _ $) is escaped. A paper with more than 100 authors lists the first 100 (BibTeX adds `and others`). The export is never cut in the middle of a record: `truncated` says that records were left out; `next_skip` (query) or `remaining` (ids) say where to continue. Nothing is written to disk.
idsskiplimitqueryfieldsformatmax_charsinclude_abstractGet papers in batch
Look up many papers at once: one combined Europe PMC query per 50 identifiers instead of one call per paper. Every input gets a result in the order given, with a status: ok, not_found, invalid (malformed identifier) or error (that request failed). One bad identifier never fails the batch; a repeated identifier repeats its result.
idsrequiredfieldsGet full text of several papers
Markdown full text of several open-access papers in one call, within a size budget. The identifiers are resolved with one query, papers that are not open access are reported without being downloaded, and the rest are fetched four at a time. The total budget is handed out in the order given: once it is used up, the remaining papers are reported as skipped_budget and not downloaded. Each result has a status: ok, not_found, invalid, not_in_pmc, not_open_access, no_matching_section, duplicate, error or skipped_budget. Use `get_paper_fulltext` for one paper at a larger size.
idsrequiredsectionsmax_total_charsmax_chars_per_paperDownload PDFs
Save the PDFs of several papers on the machine the server runs on. Files go to PYEUROPEPMC_MCP_DOWNLOAD_DIR (default ~/Downloads/pyeuropepmc) as <PMCID>.pdf, or <DOI>-<hash>.pdf for a paper outside PubMed Central; the caller cannot choose a path. A PMC paper is looked for at NCBI's open-access copy and Europe PMC; any paper with a DOI also at arXiv, OpenAlex, Semantic Scholar and, with UNPAYWALL_EMAIL set in the server's environment, at the open copy Unpaywall knows. Only open copies are fetched; a paper that has none comes back as no_pdf. It is checked to be a PDF and under 100 MB, or discarded. Returns the path, size and SHA-256 of every file, the source that supplied it and the licence that source (or, failing that, Europe PMC) reported; each saved file also gets a line in manifest.jsonl in the same folder. The PDFs stay on the server's disk: with a remote HTTP server they are not sent to the caller. Each result has a status: ok, exists (already saved, not fetched again), not_found, invalid, not_in_pmc, duplicate, no_pdf or error. Use `get_paper_fulltext` to read a paper instead of saving it.
idsrequiredoverwriteFind open-access copies
Where can this paper be read for free? Looks the DOI up in Unpaywall and returns the open-access status (gold, green, hybrid, bronze, closed), the best copy with its PDF link and licence, and a few alternatives. ``europepmc_fulltext`` says whether `get_paper_fulltext` will work for it. Needs UNPAYWALL_EMAIL in the server's environment.
doipmidpmcidGet paper annotations
Genes, proteins, chemicals, diseases, organisms and other entities that Europe PMC text-mined from a paper, grouped by entity with mention counts, sections and example mentions. A review with hundreds of mentions comes back as a short entity list.
doipmidlimitpmcidsectionproviderannotation_typeFind papers by entity
Articles in which Europe PMC found a given entity, with how often and where it is mentioned. One page per call: pass ``next_cursor`` back as ``cursor`` for the next. Europe PMC's entity search ignores type, section and provider, so the three filters here apply to the mentions it returns: an article without a matching mention is left out and counted in ``articles_filtered_out``.
limitcursorentityrequiredsectionproviderannotation_typeGet paper data links
Where is the data of this paper? Accession numbers Europe PMC text-mined from the full text (dbSNP, RefSeq, OMIM, ClinicalTrials.gov, cited DOIs) and records that providers link to the paper (BioStudies supplementary data, model-organism databases, Altmetric), as one flat list. `kind` separates supporting_data and related_data from altmetrics and recommended_reviews; `origin` says whether a link was text_mined or supplied by a provider. A paper without links gives an empty list, which is a valid answer.
doipmidlimitpmcidschemecategoryGet paper lab links
Links that third parties publish for a paper, grouped by provider with the provider's description: BioStudies supplementary material, model-organism databases, GO annotations, Faculty Opinions recommendations, Altmetric. Use get_paper_data_links for the data accessions mentioned in the text.
doipmidpmcidproviderEnrich a paper from several sources
One compact record for a paper from Europe PMC, Crossref, OpenAlex, Semantic Scholar, iCite and Unpaywall, merged: citation impact, funders and grants, authors with their institutions, open-access status and licence, and corrections and retractions. The sources are asked at the same time; `sources` in the answer says for each whether it answered (ok), had nothing (empty), failed (error, with the reason), or was still running when `time_budget` ended (timeout). A failed source gives a partial record, not an error. Institutions come with name, country and ROR ID; `ror_details` adds their place and website. Nothing is written to disk.
doipmidpmcidincludesourcesror_detailstime_budgetDecompose a research question
Split a research question into PICO, PICOS, PICOT or SPIDER elements and build a Europe PMC query from them. Rule-based and offline: no model, no key, no request. Every element is a verbatim piece of the question, given with its position; an element the question does not state is listed in `missing`, never filled in. The rules cover the usual clinical phrasings ("In P, does I reduce O compared with C?", "What is the effect of I on O in P?", "Is I more effective than C for O?", "Is I associated with O?", "Effectiveness of I for O in P", "P treated with I"). A question phrased differently is only partly understood: check `elements` and `missing` before using the query, and ask for clarification when the question is incomplete. The query is checked with the same linter as `validate_query`.
meshquestionrequiredframeworkquery_elementsExpand terms with MeSH
MeSH headings for search terms: the descriptor (ID, heading, tree numbers), its entry terms and a ready Europe PMC fragment `(MESH:"Heading" OR "entry term" OR ...)` for each term, and the fragments joined into one query that is checked like `validate_query`. By default it works offline from a bundled snapshot of 244 common clinical headings taken from NLM's published MeSH (heading, entry terms and tree numbers as published): a term that is not in it comes back with `matched: false` and is searched as written, never guessed. `use_api` asks NLM instead, which covers all of MeSH and needs the network (the terms are sent to id.nlm.nih.gov); a failed or skipped request is reported for that term and does not fail the call, and `time_budget` bounds the whole call.
termsrequiredcombineuse_apitime_budgetmax_entry_termsAnalyze a search
Aggregate statistics about a search without returning its records. Every metric says where it comes from in `basis`: `exact` is counted by Europe PMC over all `hit_count` records (`by_year`: one count per year; `open_access`; the `thresholds` of `citations`), `sample` is computed from the first `limit` records of the search and describes only those (`journals`, `authors`, `types`, `countries`, `funders` and the `citations` statistics). When `limit` covers the whole result, those are `exact` too. The sample metrics need `pip install pyeuropepmc[analytics]`.
sortlimitqueryrequiredtop_nsourcedate_tometricsdate_fromopen_accessyear_windowhas_fulltextAnalyze citation context
Analyze citation context for a paper using an LLM (requires an LLM provider).
pmidrequiredtaskcontextCompare two papers' citations
Compare citations between two papers using an LLM (requires an LLM provider).
taskpmid1requiredpmid2requiredSummarize citation activity
Summarize citation activity for a paper using an LLM (requires an LLM provider).
pmidrequiredcitation_countPRISMA paper screening
Automated paper screening with PRISMA-compliant criteria, using an LLM (requires an LLM provider).
limitqueryrequiredexclusion_criteriarequiredinclusion_criteriarequiredAnalyze a research question
Expand and analyze a research question using an LLM (requires an LLM provider).
time_frameresearch_questionrequiredPreprint quality assessment
Preprint-specific quality assessment using an LLM (requires an LLM provider).
pmidrequiredpreprint_serverGenerate a literature review
Generate a comprehensive literature review using an LLM (requires an LLM provider).
time_framekey_conceptsrequiredresearch_topicrequiredexcluded_topicsBuild a knowledge graph
Build a knowledge graph from research literature using an LLM (requires an LLM provider).
entitiesrelationshipsresearch_domainrequiredParse BibTeX
Parse a BibTeX string into structured entries.
contentrequiredValidate BibTeX
Validate BibTeX entries for completeness and correctness.
contentrequiredConvert BibTeX to RIS
Convert BibTeX entries to RIS format.
contentrequiredConvert BibTeX to CSL-JSON
Convert BibTeX entries to CSL-JSON format.
contentrequiredResolve a DOI
Resolve a DOI to bibliographic metadata.
doirequiredResolve a PMID
Resolve a PubMed ID to bibliographic metadata.
pmidrequiredMerge BibTeX libraries
Merge multiple BibTeX libraries, deduplicating by DOI.
librariesrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
pip install pyeuropepmc # corepip install "pyeuropepmc[analytics,visualization]" # add extras (quote the brackets)pip install "pyeuropepmc[all]" # every optional featurefrom 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 itparser = 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 RAGchunks = []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")pyeuropepmc unified_search search "CRISPR base editing" --limit 10 --output results.jsonpyeuropepmc benchmark list-datasetspyeuropepmc-mcp # stdio, for Claude Desktop and similar clientspyeuropepmc mcp # the same server, through the CLIpyeuropepmc-mcp --transport streamable-http # HTTP at http://127.0.0.1:8000/mcp{ "mcpServers": { "pyeuropepmc": { "command": "pyeuropepmc-mcp" } }}claude mcp add pyeuropepmc -- uvx pyeuropepmc mcppyeuropepmc benchmark run local --local-path benchmark_xmls/xml --limit 55pyeuropepmc benchmark download PLOS_1000 # 1,000 articles, 1.3 GBpyeuropepmc benchmark run PLOS_1000pytest tests/benchmark_article_client.py::test_modular_benchmark_system -m benchmark --force-enable-socket --timeout=3600@software{pyeuropepmc, author = {Heinicke, Jonas}, title = {{PyEuropePMC}: a Python toolkit for Europe PMC}, url = {https://github.com/JonasHeinickeBio/pyEuropePMC}}