跳到主要内容

med-research-mcp

Med Research MCP 是面向 AI 代理的循证文献检索 MCP 服务器,支持 PubMed、Europe PMC、ChinaXiv 和 RussiaRxiv。

安装
真实输出:一个问题、四个数据库、十秒。
真实输出:向助手提问替尔泊肽是否有助于阻塞性睡眠呼吸暂停,它检索各数据库,返回标有研究设计与警示标记的文献卡片。

med-research-mcp 是一个 MCP(模型上下文协议)服务器。它让 AI 助手能够检索 PubMed、Europe PMC 和 ChinaRxiv(含 ChinaXiv 与 RussiaRxiv 数据源),并告诉助手每条结果属于哪一类研究。这样,助手在回答之前就能分清 Meta 分析和病例报告,也能识别出已撤稿的论文。它专为医学、临床和膳食补充剂研究而设计:在这些领域,“证据究竟说明了什么”比一串摘要更重要。

  • 一次检索覆盖四个数据库,结果合并并去重。
  • 研究设计标注来自美国国家医学图书馆(NLM)的元数据:每条结果都注明它属于哪类研究、这种设计在证据等级中处于什么位置,以及是否已被撤稿或更正。不做猜测:没有相应元数据的记录标为 unknown。
  • 摘要不够时可获取全文,途径包括开放获取版本、你所在机构的代理或 DOI;ChinaXiv 和 RussiaRxiv 的论文还可获取 ChinaRxiv 提供的机器翻译全文。
  • 智能体技能(Agent Skills),教助手编写精确的检索式、解读标注并评价证据。
  • 不调用大语言模型,无需账号,不发送遥测数据。服务器在你自己的电脑上运行。

重要提示:本工具是科研辅助工具,不构成医疗建议,也不是诊断工具。请勿在检索内容中输入任何可识别患者身份的信息:检索内容会发送到隐私一节列出的数据库。另请参阅医学免责声明。

预期用途与排序说明

预期用途:本工具是面向科研与教育的学术文献检索工具,用于检索 PubMed、Europe PMC、ChinaRxiv 等数据库中已发表的科学文献,依据文献元数据标注研究设计类型,并获取可公开获取的全文,或在用户自行配置时经其所在机构获取的全文。本工具不用于任何疾病的诊断、预防、监护、治疗或者缓解,不提供用药指导或治疗建议,不用于针对具体患者的诊疗决策,不处理患者数据,不作为医疗器械使用。研究设计标注仅反映文献的索引信息,不代表研究结论可靠或适用于任何个人。如有健康问题,请咨询医生。

排序说明:检索结果按研究设计等级排序(依据牛津循证医学中心 2011 年证据等级与美国国家医学图书馆的文献类型标注):设计等级 5 至 2 级的文献依次排在最前,其次为未评级的文献,最后为 1 级和 0 级的文献;同一等级内保留各数据库的原始顺序。不使用个人数据,不做个性化推荐。

安装

需要 Node.js 22.22.2 或更高的 22.x 版本、24.15.0 或更高的 24.x 版本,或 26 及以上版本。服务器直接从 npm 运行,无需克隆仓库或构建。请将示例中的 [email protected] 替换为你的邮箱(见配置)。

Claude Code

claude mcp add med-research-mcp -s user \
  -e [email protected] \
  -- npx -y med-research-mcp

-s user 使它在你的所有项目中可用。运行 claude mcp get med-research-mcp 可检查连接;工具会在新会话中出现。

Claude Desktop

从最新发布版本下载 med-research-mcp.mcpb,拖到 Claude Desktop 上即可。安装程序会提供几项可选设置(例如你的邮箱),无需编辑任何 JSON。

Cursor、Windsurf、Cline 等客户端

将以下内容添加到客户端的 MCP 配置中:

{
  "mcpServers": {
    "med-research-mcp": {
      "command": "npx",
      "args": ["-y", "med-research-mcp"],
      "env": { "NCBI_EMAIL": "[email protected]" }
    }
  }
}

使用 YAML 配置的客户端(如 Hermes)填写相同的 command、args 和 env 即可。

魔搭社区(ModelScope)

本服务器也已在魔搭社区上架,可由魔搭托管运行,无需在本地安装任何软件。

从源码安装

git clone https://github.com/emilkrebs/med-research-mcp.git
cd med-research-mcp
npm install
npm run build

然后将 node /path/to/med-research-mcp/dist/mcp/index.js 用作启动命令;运行 npm run build:mcpb 可构建 Claude Desktop 安装包。如需将服务器作为团队共享的 HTTP 服务运行,请参阅 docs/hosting.md(英文)。

配置

以下变量在 MCP 客户端配置的 env 中设置。它们都是可选的,但请设置 NCBI_EMAIL。

变量作用
NCBI_EMAIL你的联系邮箱。按照 NCBI 使用政策的要求,它会随每个 NCBI(PubMed)请求一起发送,以便 NCBI 在封禁超出限额的 IP 之前联系你。未单独设置 Unpaywall 和 ChinaRxiv 的邮箱时,也用于这两项服务。如未设置,发往 NCBI 和 Unpaywall 的请求会改为附带本项目的联系邮箱。
NCBI_API_KEY将 PubMed 的速率上限从每秒 3 次请求提高到 10 次。可在 NCBI 账户设置中获取。
MED_RESEARCH_UNPAYWALL_EMAILUnpaywall 的联系邮箱。Unpaywall 用于查找开放获取的全文。
MED_RESEARCH_CHINAXIV_EMAILChinaRxiv 的联系邮箱。ChinaRxiv 提供 chinaxiv 和 russiarxiv 两个数据源;设置后,其速率上限从每分钟 30 次请求提高到 300 次。
MED_RESEARCH_PROXY_PREFIX你所在机构用于 doi.org 的 EZproxy 地址,例如 https://doi-org.ezproxy.your-university.edu,用于阅读你有权访问的付费论文。仅当该代理无需登录即可放行本机时才有效,例如在校园网内或通过 VPN 连接时。请仅在机构的许可协议允许时使用:许多出版商禁止将订阅内容用于 AI 工具。
MED_RESEARCH_FULLTEXT_MAX_CHARS全文每一部分的最大长度(字符数):较长的全文分段返回,用 offset 接着读取。默认为 50000。
MED_RESEARCH_FULLTEXT_ALLOW_PRIVATE设为 1 时,允许获取全文的请求访问私有或保留网络地址(服务器默认拒绝)。仅当个人电脑使用 fake-IP 模式的 DNS 代理(如 TUN 模式下的 Clash、Surge 或 sing-box)或分离解析(split-horizon DNS)时才需要;切勿在共享服务器上设置。
MED_RESEARCH_CACHE_BACKENDmemory(默认)或 sqlite;后者在重启后仍保留缓存。
MED_RESEARCH_CACHE_PATHsqlite 后端使用的 SQLite 文件。请使用绝对路径:默认值 ./pubmed-cache.db 是相对于客户端启动服务器时所在目录的路径。

.env.example(英文)逐一说明了上述变量,以及 HTTP 服务器的变量。

工具

工具作用
literature_search检索一个或多个数据库,并为每条结果标注研究设计、设计等级和警示标记。
literature_fetch返回指定论文的完整记录和摘要。
literature_fulltext输入 PMID、PMCID、预印本编号或 ChinaXiv、RussiaRxiv 编号,以 Markdown 格式返回论文全文:能找到开放获取或已获授权的版本时返回该版本,ChinaXiv 和 RussiaRxiv 的编号则返回 ChinaRxiv 的机器翻译文本。

助手通常先检索,再阅读有价值的摘要,在需要研究方法、剂量或样本量时获取全文。全部参数见 docs/tools.md(英文)。

每条结果上的标注含义如下:

  • studyType(研究类型)是 NLM 标引的研究设计,例如 meta-analysis(Meta 分析)、randomized-controlled-trial(随机对照试验)、case-report(病例报告)等;记录没有此类元数据时为 unknown。unknown 表示未标注,不代表证据弱。这种情况在新近发表的论文、未被 MEDLINE 收录的期刊以及 ChinaXiv 和 RussiaRxiv 数据源中很常见;对于这些论文,助手会自行阅读摘要。
  • designTier(设计等级)参照牛津循证医学中心(OCEBM)证据等级,针对“这种治疗是否有效?”这类问题为研究设计排序,从 5 级(随机试验的系统综述)到 0 级(动物和实验室研究、已撤稿论文)。它只为研究设计分级,不评价研究本身的质量。元数据无法确定设计时,该值为 null:包括未标注的记录,以及大多数 Meta 分析——它们的等级取决于所合并的研究。null 表示未评级,不代表证据弱。
  • flags(警示标记)提示撤稿、更正、关注声明、预印本和机器翻译文本。

ChinaXiv 和 RussiaRxiv 的记录来自 ChinaRxiv。这是一个独立项目,与中国科学院的 ChinaXiv(中国科学院科技论文预发布平台)没有关联。ChinaRxiv 的英文文本由机器翻译,大多数 RussiaRxiv 摘要也是它自行撰写的;在依据其中的剂量、研究人群或结局之前,请核对原始记录。

隐私

服务器在你的电脑上运行,不发送遥测数据。你的检索内容会发送到你所检索的数据库(PubMed 由 NCBI 提供,Europe PMC 由 EMBL-EBI 提供,此外还有 ChinaRxiv),获取全文的请求还可能把文献编号或 DOI 发送到你并未检索的服务:NCBI、Europe PMC 或 ChinaRxiv(查询该编号的记录、获取全文)、Unpaywall、doi.org、出版商或存储库的网站,以及你配置的机构代理,它们各自适用其服务条款和隐私政策。检索结果缓存在你的电脑上,默认保存在内存中,除非你选择 SQLite。如果你使用他人运行的 HTTP 实例,其运营方也会收到你的检索内容。请勿在检索内容中输入姓名、病历号或其他可识别患者身份的信息。详见 docs/compliance.md(英文)。

文档

以下文档均为英文。

  • 工具参考:参数、结果、数据库、标注和错误。
  • 工作原理:检索流程、研究设计标注的分配方式及其依据、全文获取、缓存,以及基准测试如何为回答评分。
  • 托管部署:为团队通过 HTTP 运行服务器。
  • 使用核心库:不经 MCP,直接调用相同的功能。
  • 合规:预期用途、数据流向,以及所调用服务的条款。
  • 开发:构建、测试和发布。
  • 基准测试:各模型借助本服务器回答生物医学问题的表现。
  • 版本发布:每个版本的变更。

医学免责声明

med-research-mcp 是面向科研与教育的文献检索工具。它不提供医疗建议、诊断或治疗建议,不用于针对具体患者的诊疗决策,也不是医疗器械。其研究设计标注只对研究的设计方式进行分级,既不评价单项研究的质量,也不表示其结果适用于任何人。这些标注不能替代临床判断,也不能替代具备资质的专业人员。请务必对照原始文献核实研究发现,并在做出医疗或膳食补充剂相关决定之前咨询医生。

数据来源与版权

PubMed 数据由美国国家医学图书馆(NLM)通过美国国家生物技术信息中心(NCBI)的 E-utilities 提供,适用 NCBI 的免责声明和版权声明。NLM 不主张 PubMed 摘要的版权,但摘要的出版商或作者可能主张;NLM 也不为本工具背书。Europe PMC 数据来自 Europe PMC REST API(EMBL-EBI),适用 EMBL-EBI 使用条款。开放获取版本的位置信息来自 Unpaywall。ChinaXiv 和 RussiaRxiv 的记录来自 ChinaRxiv API,其接口规范声明采用 CC BY 4.0 许可。全文归其权利人所有,请在相应许可范围内使用。

许可证

MIT。

智能体技能

三个技能教助手用好这些工具。可在此阅读,也可下载需要的那个用于你自己的客户端。

med-research工作流程:编写精确的 PubMed 检索式、解读标注、判断未标注论文的研究类型,并在报告研究发现时说明其确定程度。阅读 SKILL.md

Use when researching biomedical, supplement, peptide, or longevity evidence with the med-research-mcp MCP server (tools literature_search, literature_fetch, literature_fulltext). Covers writing precise PubMed queries with field tags, reading study designs (studyType, 0-5 designTier, flags), classifying unlabeled papers from the abstract, the ground rules of weighing evidence, choosing between search/fetch/fulltext, multi-database searches, and how to report findings. Three few-shot patterns (lookup, synthesis, bullshit) show the exact workflow. Trigger on questions about what the research/evidence says for a compound, dose, intervention, or biomarker.

Using the med-research-mcp MCP

Three tools, a triage-first workflow. Always start with literature_search (free, designs labeled from NLM metadata), drill into papers with literature_fetch, and use literature_fulltext only when the abstract isn't enough.

Decision flow

  1. Turn the question into a query (below) and call literature_search. Default database is "pubmed"; for broader coverage use ["pubmed","europepmc"], ["pubmed","chinaxiv"], or "all". For a preprint or a paper outside MEDLINE search "europepmc" alone (SRC:PPR keeps preprints only; PubMed reads it as words and has the NIH-supported ones). "russiarxiv" is Soviet-era papers, mostly mathematics, physics and chemistry, almost no medicine: a zero there is not "no Russian research exists".
  2. Read warnings and flags first. Then read the abstract of every result whose designTier is null: unclassified records and most meta-analyses/systematic reviews. Null means unrated, not weak.
  3. literature_fetch the ids you care about (with their database) to read whole abstracts.
  4. literature_fulltext only when the abstract isn't enough: dosage, sample sizes, methods, statistical flaws.
  5. Europe PMC records indexed in MEDLINE carry the same NLM labels as PubMed. Its preprints (PPR…) and CBA:… records have no design tag, so they are unknown, like all ChinaXiv/RussiaRxiv records — you classify them. ChinaXiv/RussiaRxiv come through ChinaRxiv, a third-party service; ChinaXiv records are preprints.

2–5 keywords, never a sentence: every word must match, so each extra word narrows the result. On 0 results the warning names the word that blocks a query of plain words (no quotes, tags or operators), or says no single word does (use fewer, more general words); with tags, drop one clause at a time. PubMed ignored "word" means no record contains it: check the spelling. PubMed has no phrase "…" means PubMed found no such phrase and searched its words separately, anywhere in a record. Tags and booleans add precision on PubMed and Europe PMC; chinaxiv/russiarxiv ignore them.

  • [tiab] — title/abstract (most precise): zinc[tiab] AND ("common cold"[tiab] OR rhinovirus[tiab]). Quote a phrase before its tag or tag each word: Europe PMC drops the tag of common cold[tiab].
  • [mesh] — controlled MeSH, PubMed only: "Zinc"[mesh] AND "Common Cold"[mesh]
  • [au] — author: Hemilä H[au]
  • [pt] — publication type, for strong designs: AND (meta-analysis[pt] OR "randomized controlled trial"[pt])
  • Europe PMC reads [tiab] [ti] [au] [pt] [ta] [la] [dp] [pmid] and drops other tags, so their words match full text.
  • chinaxiv/russiarxiv return only records containing every word, and read OR as a word: give them one or two key words.

Params (the tool descriptions have the rest):

  • maxResults (default 10, max 50) counts per database and page: two databases return up to 20.
  • abstractMaxChars cuts abstracts to that many characters (0 leaves them out). Ten whole abstracts run 20,000–30,000 characters: with several databases or many results set one (600 halves it). abstractTruncated: true (also on ChinaXiv/RussiaRxiv previews, cut at 500 characters) means literature_fetch the record for the whole abstract.
  • page: pass a result's nextPage with the same maxResults to read on. Each page is sorted on its own.
  • studyTypes (e.g. ["meta-analysis","systematic-review","randomized-controlled-trial"]): use this to keep reviews and trials. cohort, case-control, cross-sectional and in-vitro never match.
  • minDesignTier (4 = RCTs): drops every null tier, including most meta-analyses; read the warning.

Reading the design labels (GradedArticle)

studyType comes only from NLM PublicationType tags — no text guessing. NLM now assigns them by automated indexing, with human review of only some records, so treat them as a strong prior: confirm in the abstract when it matters. † marks what only you assign, from the abstract: the tool never returns tier 3, gives 5 only to a Network Meta-Analysis tag, and never names cohort, case-control, cross-sectional or in-vitro (tagged observational studies come back as observational). designTier ranks the design for "does this intervention help?" by the OCEBM 2011 levels [1] — a prior, not an appraisal.

designTierstudyTypeReading
5meta-analysis / systematic-review of randomized trials †most reliable design for treatment effects; a review of weak trials is still weak
4randomized-controlled-trialrandomized comparison. NLM also tags secondary/post-hoc analyses of trials this way — check that the comparison you cite is the randomized one
3cohort †observational with a comparison group; confounding likely
2non-randomized-trial · clinical-trial · observational · case-control † · cross-sectional †controlled but not randomized (historical controls possible) · a trial whose randomization and control aren't indexed (may be single-arm) · an observational study of unindexed design · hypothesis-generating designs
1case-report · reviewanecdote · review article not indexed as systematic (16% of 2023 papers titled "systematic review" carry only this tag — check)
0animal-study · in-vitro †, or any record flagged retracted / notice / protocol / editorialnot usable as evidence for human benefit
nullmeta-analysis / systematic-reviewwhat it pooled isn't in the metadata — read the abstract: of RCTs → tier 5; of observational studies → the tier of those studies
nullunknownno design metadata, not weak — recent, non-MEDLINE or regional record; classify it yourself

flags — tier 0: retracted (never cite as support), notice (a retraction notice, expression of concern or erratum, not a study), protocol (planned study, no results), editorial (opinion or commentary). Warnings, tier unchanged: expression-of-concern (the journal doubts its integrity; don't rely on it alone), corrected (an erratum exists — check the numbers you quote), updated (a newer version exists: an updated Cochrane review, or a preprint's published article, whose id is in corrections — cite that one, fetching it if needed), animals-not-humans (MeSH lists animals but not humans; usually an animal study, but automated indexing sometimes drops the Humans tag from real human trials [9] — check the abstract), preprint (not peer reviewed), letter (may be correspondence or a short research report), machine-translated (ChinaXiv/RussiaRxiv text is a machine translation — confirm numbers in originalUrl), machine-generated-abstract (the abstract is ChinaRxiv's summary, not the authors' — never quote it as the paper's findings). Dosage, population, sample size and limitations are not extracted — read them in the abstract.

Classifying from the abstract

Use the same labels. Do it for unknown results, and refine clinical-trial, observational and unrated syntheses. Classify the paper's own design, not designs it mentions ("previous RCTs showed…", "further trials are needed" describe other work). Reporting guidelines ask authors to name the design in the title or abstract [10].

  • Pooled studies found by a stated search → meta-analysis (pooled numerically) / systematic-review, and note what designs it pooled. An unsystematic overview → review.
  • Investigators assigned the intervention: randomly → randomized-controlled-trial; with a non-random control group → non-randomized-trial; single-arm → clinical-trial (rank it like a case series).
  • Observed only: groups compared over time → cohort; cases compared with controls → case-control; one time point or a survey → cross-sectional; one or a few patients → case-report.
  • Animals or cells only, no human participants → animal-study / in-vitro, even if randomized.
  • Future tense ("we will randomize"), "protocol" → a protocol, not results. Unsure between two designs → take the lower one.

Say when a design is your reading of the abstract, not a database label.

Ground rules of evidence

Apply these to every answer, not only pivotal ones.

  1. Design is the starting point, not the verdict. Certainty drops for risk of bias, imprecision, inconsistency, indirectness and publication bias [2], and can rise for a large effect [1] or a dose–response gradient [3].
  2. The best design depends on the question. Treatment benefit: randomized trials. Harms: randomized trials too, but rare or long-term harms often show only in large observational follow-up (post-marketing surveillance). Prognosis: inception cohorts. Diagnostic accuracy: cross-sectional studies against a reference standard [1]. The tier assumes a treatment-benefit question.
  3. Association is not causation. Observational studies show associations that confounding or reverse causation can explain. Weigh causal claims with the Bradford Hill considerations, none of which settles causation on its own [3]; a cause must precede its effect, so always check temporality.
  4. Absence of evidence is not evidence of absence. No trial found, or a non-significant result with a wide confidence interval, means "unknown", not "doesn't work" [4].
  5. Weigh all the evidence, not the study that agrees. Search for null and negative results too, and prefer systematic reviews. Small, single, surprising or implausible positive findings are often false [5].
  6. Effect size and relevance over p-values. Report absolute effects with confidence intervals; a statistically significant change can be clinically irrelevant [1].
  7. Improvement without a control group proves little. Regression to the mean [6] and placebo effects, which can influence patient-reported outcomes such as pain and nausea [7], make before–after studies and single-arm trials look effective.
  8. Directness. The population, intervention and dose, comparator and outcome must match the question; surrogate outcomes and animal data are indirect [8].
  9. Newer, larger trials can overturn earlier evidence. Large RCTs agreed only fairly with earlier meta-analyses (κ = 0.35) [11], and 40% of established practices tested in one major journal over 10 years were reversed [12]. Check dates; prefer the latest systematic review.
  10. State certainty honestly. Use GRADE's levels [2] and matching wording: "results in" (high), "likely results in" (moderate), "may result in" (low) [13]; for very low certainty say the evidence is very uncertain.

Tools, limits, errors

  • literature_fetch({ids:["39123456","38987654"], database:"pubmed"}) — 1–50 ids of one database (a result's id and database): whole abstracts, publication types, MeSH, retraction/correction links, and the same studyType/designTier/flags as search.
  • literature_fulltext({id:"39123456"}) — article body as markdown via Europe PMC (records with a pmcid) → Unpaywall → proxy → DOI; otherwise the abstract, and warning says why. A result's id works alone, with its prefix (CBA:644599; a bare number is a PMID); doi is only for an id Europe PMC doesn't know; a url is not a DOI. warning opens with RETRACTED:, NOTICE: or EXPRESSION OF CONCERN: when the record has that flag, even if the text came (say so first); it reads the record as the databases report it at the time, so the flags of search or fetch are the authority. A long text comes in parts: while truncated is true, call again with offset: nextOffset.
  • NCBI is rate-limited: parallel calls are safe but don't run faster. Prefer a few precise queries.
  • Errors: QUERY_TOO_BROAD (narrow: add a [tiab] term or an AND clause); RATE_LIMIT (the server already retried; wait retryAfter); NETWORK_ERROR/PARSE_FAILURE (retry once, then say the DB is unreachable); TIMEOUT (retry, then ask for an earlier page or narrow the query); INVALID_INPUT and schema errors (fix the parameter named: database ids are lower case, dates must exist). In a multi-database search, a database that fails while others answer shows up only in warnings (<database> search failed: …): say which is missing, never report it as "no studies found".

Reporting

Lead with the strongest evidence, its design and how certain it is; summarize consensus, then contradictions. If a record you rely on is flagged retracted, notice or protocol, the answer's first sentence says so. Cite the id the tool returned, as "PMID …" only when the record has pmid, otherwise with its database (PPR…, chinaxiv-…) or the doi/url; never type an id from memory. Report doses and populations as what the studies used and found, quoted from the abstract or the full text you read (say which), not as recommendations, and call out animal-only, tiny or abstract-less results. Surface the other flags (expression of concern, updated, preprint, machine-translated) and what you read yourself (COI, n<20). This is a research summary, not medical advice: say so when the question is about dosing or treatment, and point to a healthcare professional for decisions about a person's care.

Three patterns (follow these, don't ad-lib)

1. Simple lookup — known PMID

"What study design is PMID 22570464, and how strong is that design?"

One call, no fan-out: literature_search({query:"22570464[pmid]"}) — it returns studyType, designTier, flags and the abstract. If flags has retracted/notice/protocol, say so first. If designTier is null, read the abstract: for a synthesis, find what it pooled; for unknown, classify it (above) and say so. Answer: "Systematic review and meta-analysis of randomized controlled trials — 82 met the inclusion criteria, 63 were pooled (NLM tag; pooled designs from the abstract): design tier 5 of 5 (PMID 22570464)." Stop.

2. Evidence synthesis — compare X vs Y

"Compare intranasal corticosteroids vs oral antihistamines for allergic rhinitis symptoms. Which has stronger evidence, and why?"

Frame PICO, then two targeted searches (one per arm, study-type filter): "intranasal corticosteroid*"[tiab] AND "allergic rhinitis"[tiab] AND (meta-analysis[pt] OR "randomized controlled trial"[pt]), and "oral antihistamine*"[tiab] AND "allergic rhinitis"[tiab] AND (...). literature_fetch the top 2–3 ids per arm; read what each review pooled, effect sizes + CIs, n, I². Judge which arm's evidence is more certain, not which effect is bigger: start from design (a meta-analysis of RCTs beats one small RCT), then rate down as in ground rule 1. Name which arm is stronger and why; cite ids; state certainty in GRADE terms. Cap at ~6 calls.

3. Bullshit detection — the study doesn't exist

"Summarize the 2020 Nilsen trial on taurine and slow-wave sleep."

Search author+topic, then title terms, then both databases: Nilsen[au] AND taurine AND sleep; taurine slow-wave sleep 2020; taurine slow-wave sleep Nilsen with database: ["pubmed","europepmc"]. Nothing corroborating after these three queries → STOP — don't keep reformulating 8–10 times and return empty. Answer plainly, naming the databases searched (databases in the result): "I could not find this trial in PubMed or Europe PMC; it does not appear to exist." Invent no id, cite no fabricated study. Suggest the user double-check the reference.

Small-model tips

  • Budget your calls: 1 for a lookup, ~4–6 for synthesis, three queries (pattern 3) before you say nothing was found. Then stop and say so: never return an empty answer; a caveat beats silence.
  • Lead with the bottom line: the winner or number first, then design, certainty, citation, flags.

When to go deeper (EBM)

The 0–5 design tier orients you; it does not appraise a study. When a conclusion will rest on one paper and you need risk-of-bias (RoB 2 / ROBINS-I), AMSTAR 2, effect sizes/CIs/NNT, heterogeneity, Bradford Hill causation, or applicability checks, load the med-research-ebm reference skill. Don't load it for routine searches — it's heavy.

References

  1. OCEBM Levels of Evidence Working Group. The Oxford 2011 Levels of Evidence, and its Introductory Document. Oxford Centre for Evidence-Based Medicine. https://www.cebm.ox.ac.uk/resources/levels-of-evidence/ocebm-levels-of-evidence
  2. Balshem H, et al. GRADE guidelines: 3. Rating the quality of evidence. J Clin Epidemiol 2011;64:401-6. PMID 21208779
  3. Hill AB. The environment and disease: association or causation? Proc R Soc Med 1965;58:295-300. PMID 14283879
  4. Altman DG, Bland JM. Absence of evidence is not evidence of absence. BMJ 1995;311:485. PMID 7647644
  5. Ioannidis JPA. Why most published research findings are false. PLoS Med 2005;2:e124. PMID 16060722
  6. Barnett AG, et al. Regression to the mean: what it is and how to deal with it. Int J Epidemiol 2005;34:215-20. PMID 15333621
  7. Hróbjartsson A, Gøtzsche PC. Placebo interventions for all clinical conditions. Cochrane Database Syst Rev 2010;CD003974. PMID 20091554
  8. Guyatt GH, et al. GRADE guidelines: 8. Rating the quality of evidence — indirectness. J Clin Epidemiol 2011;64:1303-10. PMID 21802903
  9. Askin N, et al. Filtering failure: the impact of automated indexing in Medline on retrieval of human studies for knowledge synthesis. J Med Libr Assoc 2025. PMID 39975499
  10. Hopewell S, et al. CONSORT 2025 statement. BMJ 2025;389:e081123 (PMID 40228833), item 1a; Vandenbroucke JP, et al. STROBE: explanation and elaboration. PLoS Med 2007;4:e297 (PMID 17941715), item 1a; Page MJ, et al. The PRISMA 2020 statement. BMJ 2021;372:n71 (PMID 33782057), item 1
  11. LeLorier J, et al. Discrepancies between meta-analyses and subsequent large randomized, controlled trials. N Engl J Med 1997;337:536-42. PMID 9262498
  12. Prasad V, et al. A decade of reversal: an analysis of 146 contradicted medical practices. Mayo Clin Proc 2013;88:790-8. PMID 23871230
  13. Santesso N, et al. GRADE guidelines 26: informative statements to communicate the findings of systematic reviews of interventions. J Clin Epidemiol 2020;119:126-135. PMID 31711912
med-research-ebm严格评价,仅在结论将取决于单篇论文时加载:偏倚风险、效应量、异质性、因果关系和适用性。阅读 SKILL.md

Load ONLY when critically appraising a study or deciding whether a paper is trustworthy enough to rely on — risk of bias (Cochrane RoB 2 / ROBINS-I / ROBINS-E), AMSTAR 2 / ROBIS for reviews, effect sizes / confidence intervals / NNT, heterogeneity (I²), prediction intervals and funnel-plot bias, Bradford Hill causation, applicability/external validity, funding and conflicts of interest, selective publication. Not needed for simple lookups or searches; load the `med-research` workflow skill for query patterns, the 0–5 design tiers and the ground rules of evidence.

EBM critical appraisal — the med-research-ebm reference

The designTier orients you; evidence-based medicine tells you what to actually trust. Run a pivotal paper through these lenses only when a conclusion will rest on it (a claim about a dose, an effect size or an outcome the user wants to rely on). For routine searches and lookups, stay in the lean med-research workflow — don't load this. Numbers in brackets refer to the references at the end.

Frame the question with PICO(S)

Before appraising, state the question explicitly:

  • Population — who (age, condition, stage, comorbidity)?
  • Intervention — what exposure, drug, dose, formulation, protocol?
  • Comparator — placebo, standard care, alternative?
  • Outcome — what patient-important endpoint (mortality, function, symptom score, QoL)?
  • (S)tudy design — what would the ideal study be (RCT, cohort, n-of-1)?

A question you cannot state in PICO form is too vague to answer with literature. Reuse the same PICO to decide whether a returned paper actually answers your question, not some adjacent one.

Hierarchy of evidence (a prior, not a verdict)

The best design depends on the question. The OCEBM 2011 levels [1], level 1 first:

QuestionLevel 1Level 2Level 3Level 4
Does this intervention help?systematic review of randomized trials, or an n-of-1 trialrandomized trial, or observational study with dramatic effectnon-randomized controlled cohort/follow-up studycase series, case-control or historically controlled studies
What are the harms?systematic review of randomized trials, or n-of-1 trial (common harms also: systematic review of nested case-control studies, or observational study with dramatic effect)randomized trial, or (exceptionally) observational study with dramatic effectnon-randomized controlled cohort/follow-up (post-marketing surveillance), with enough numbers and follow-upcase series, case-control or historically controlled studies
Prognosis (what happens without treatment)?systematic review of inception cohortsinception cohortcohort study or control arm of a randomized trialcase series, case-control, or poor-quality cohort
Is this test accurate?systematic review of cross-sectional studies with a consistent reference standard and blindingindividual such cross-sectional studynon-consecutive studies, or no consistent reference standardcase-control studies, or a poor or non-independent reference standard

Level 5 is mechanism-based reasoning (none is listed for prognosis). The table says "systematic review of randomized trials or n-of-1 trials" for level 1; OCEBM states the intended reading is "either N-of-1 randomized trials or systematic reviews of randomized trials" [1]. The tool's designTier follows the first row. A systematic review ranks with the studies it pooled: a meta-analysis of cohort studies sits at the cohort level, not level 1. OCEBM grades a level down for poor quality, imprecision, indirectness, inconsistency or a very small absolute effect, and up for a large effect [1]. GRADE starts randomized evidence at high certainty and observational evidence at low, then rates down or up [2]. Hierarchy is where you start, not where you finish.

Critical appraisal by study type

Match the appraisal tool to the design rather than applying one checklist to everything:

  • RCTs — Cochrane RoB 2 [3], five domains: bias arising from the randomization process, from deviations from intended interventions, from missing outcome data, in measurement of the outcome, and in selection of the reported result [4]. Check CONSORT 2025 reporting [5].
  • Non-randomized studies of interventions — ROBINS-I [6], seven domains (confounding, selection of participants, classification of interventions, deviations from intended interventions, missing data, measurement of outcomes, selection of the reported result); its draft Version 2 (November 2025 revision) drops the deviations domain and adds questions on immortal-time bias [6]. Non-randomized follow-up studies of exposures (e.g. diet, pollutants) — ROBINS-E [7].
  • Systematic reviews / meta-analyses — AMSTAR 2 [8] or ROBIS [9]; PRISMA 2020 for reporting completeness and the flow diagram [10].
  • Diagnostic accuracy — QUADAS-3 [11].
  • Prognostic factors — QUIPS [12].
  • Case reports — the CARE reporting guideline [13].

Generic red flags across all designs: lack of randomization, unblinded subjective outcomes (placebo interventions can influence patient-reported outcomes such as pain and nausea [14]), post-hoc subgroup "discoveries", per-protocol instead of intention-to-treat analysis, and outcome switching versus the registered protocol.

Statistics: effect size and clinical significance

  • Prefer effect sizes with 95% confidence intervals over bare p-values. A tiny effect can reach p<0.05 in a large sample and still be clinically irrelevant [1]. A CI that spans both benefit and harm means the effect is uncertain — not that there is none [15].
  • RRR vs ARR vs NNT: a relative risk reduction sounds large even when the absolute benefit is small; the absolute risk reduction grounds it. NNT = 1/ARR — the number of patients you must treat to prevent one event.
  • Know the MCID (minimal clinically important difference) for the outcome [16]. A statistically significant 0.3-point gain on a 100-point scale is rarely worth a drug's harms and cost.
  • SMD / Cohen's d for continuous outcomes: Cohen's conventions are 0.2 small, 0.5 medium, 0.8 large [17] — rough guides; always translate back to the outcome's native units.
  • Surrogate endpoints (biomarker, lab value, imaging) are indirect evidence for patient-important outcomes (mortality, function, quality of life) [26], and trials using surrogates report larger treatment effects than trials using patient-relevant outcomes (pooled odds ratio 0.51 vs 0.76) [18]. Confirm the hard endpoints.
  • Non-inferiority trials answer a different question than superiority; always check the non-inferiority margin, which is easily set too wide.
  • Watch for multiplicity: many tested outcomes or subgroups make some p<0.05 by chance likely; demand a pre-specified primary endpoint and correction.

Meta-analysis-specific checks

  • What was pooled? Randomized trials, observational studies, or both? The pooled designs set the starting certainty [2].
  • Heterogeneity (I²): the Cochrane Handbook gives overlapping, rough ranges — 0–40% might not be important, 30–60% may be moderate, 50–90% may be substantial, 75–100% considerable — and warns that thresholds "can be misleading": weigh the size and direction of the effects too [19]. With high I², read the forest plot and subgroups; don't trust the diamond.
  • Prediction interval (random effects) shows the spread of true effects across settings, which the CI around the mean hides [20]. It assumes normally distributed effects and needs roughly five or more studies [19].
  • Small-study effects / publication bias: inspect the funnel plot. Tests for asymmetry (e.g. Egger's [21]) need at least 10 studies, and asymmetry is not proof of publication bias — heterogeneity, flawed small studies and chance can cause it [22, 23].
  • PICO consistency: does pooling apples and oranges actually answer one question? A meta-analysis is only as good as the studies it ingests.

Causation vs association

Observational studies show association, not causation. For causal claims weigh the Bradford Hill considerations [24]: strength, consistency, specificity, temporality, biological gradient, plausibility, coherence, experiment, analogy. Use them to weigh the evidence, not as a checklist to tick off: Hill held that none of them is a sine qua non [24]. Only temporality (exposure before outcome) follows from what a cause is, so check it every time. Confounding by indication and reverse causation are the usual suspects in pharmaco-epidemiology. Mendelian randomization [25] and natural experiments can strengthen causal inference where RCTs are unethical or impractical.

Applicability / external validity

A trial that is internally perfect but run on the wrong population does not answer your question [26]. Ask:

  • Does the study population match the population in the question (age, sex, comorbidity, disease severity, setting)?
  • Is the intervention realistic (dose, formulation, duration, adherence, setting, cost)?
  • Are the outcomes patient-important ones, measured at a meaningful time point?
  • Is the comparator current standard of care — or a straw man?

Bias beyond the single study

  • Funding source & conflicts of interest: manufacturer sponsorship of drug and device studies leads to more favorable efficacy results and conclusions, a bias that standard risk-of-bias tools don't capture [27]. Check the funding and conflict-of-interest statements and the sponsor.
  • Selective publication & outcome switching: compare the published outcomes to the registered protocol on ClinicalTrials.gov, ISRCTN, or EU-CTR; misreported outcomes are common even in top journals [28]. Missing or re-labeled outcomes are a red flag.
  • Replication & pre-registration: a single study, however good, is a hypothesis. Small, flexible, single positive studies are often false [29]. Independent replication — ideally pre-registered and by a non-conflicted group — is the real test.
  • Data integrity: gross inconsistencies, impossible variance, duplicated images, or reported means that are impossible for the sample size (the GRIM test [30]) signal errors or fabrication.

Mechanism is a prior, not proof

Mechanistic plausibility (in vitro, animal, pathway data) lowers the bar for believing an association, but bench/animal data is not human efficacy: it is level 5 at best [1] and indirect in population [26]. Use mechanism to generate hypotheses and to sanity-check implausible clinical claims — never as a substitute for outcomes in actual patients.

A short trust rule

A claim is trustworthy enough to act on when it comes from a pre-registered, well-powered, low-risk-of-bias study (or better, a consistent, low-heterogeneity meta-analysis of such studies), in a population matching the question, with a patient-important outcome, a clinically meaningful effect size and tight CI, replicated by an independent non-conflicted group, and the benefit outweighs the harms and costs in that context. Anything less is a graded hypothesis, not a fact.

Quality checklist (run when a conclusion will rest on a paper)

  1. Design and flags. designTier 4–5 is a strong design, nothing more. A flags entry of retracted, notice, protocol or editorial ends the appraisal: it is not evidence. expression-of-concern: don't rely on it alone. updated: appraise the newer version. corrected: check the erratum before quoting numbers. animals-not-humans: confirm whether humans were studied.
  2. Confirm the design yourself. studyType is NLM's label, often machine-assigned; unknown means there is none. clinical-trial and observational hide the specific design, an RCT label can be a secondary analysis, a review may be systematic, and an unrated meta-analysis needs its pooled designs read. Check the Methods.
  3. Rate down what the tier can't see. Pilot/feasibility trials, post-hoc or subgroup analyses, syntheses of observational-only or animal studies, single-centre or tiny samples, surrogate outcomes — each lowers certainty below the design's tier.
  4. Population match. Read who was studied (age, sex, ancestry, disease, setting) in the abstract. A study on healthy 20-year-olds is not directly applicable to 60-year-olds with hypertension.
  5. Dosage. Read the dose, formulation and duration from the abstract or full text; confirm units.
  6. Database source. ChinaXiv/RussiaRxiv and non-MEDLINE records carry no NLM labels. ChinaXiv/RussiaRxiv text is a machine translation (machine-translated), and most RussiaRxiv abstracts were written by the database (machine-generated-abstract). If one looks pivotal, read the original record (originalUrl) before relying on it; for other non-MEDLINE records, fetch the full text.
  7. Fetch the abstract. When in doubt, call literature_fetch with the PMID/id. Read the Methods and Results sections.
  8. Fetch the full text. For papers whose doses or effects you will report, call literature_fulltext. Check methods, sample size, statistical power, effect size, and confounders.

References

  1. OCEBM Levels of Evidence Working Group. The Oxford 2011 Levels of Evidence, and its Introductory Document. Oxford Centre for Evidence-Based Medicine. https://www.cebm.ox.ac.uk/resources/levels-of-evidence/ocebm-levels-of-evidence
  2. Balshem H, et al. GRADE guidelines: 3. Rating the quality of evidence. J Clin Epidemiol 2011;64:401-6. PMID 21208779
  3. Sterne JAC, et al. RoB 2: a revised tool for assessing risk of bias in randomised trials. BMJ 2019;366:l4898. PMID 31462531
  4. Higgins JPT, et al., eds. Cochrane Handbook for Systematic Reviews of Interventions, version 6.5, 2024, chapter 8. https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-08
  5. Hopewell S, et al. CONSORT 2025 statement: updated guideline for reporting randomised trials. BMJ 2025;389:e081123. PMID 40228833
  6. Sterne JA, et al. ROBINS-I: a tool for assessing risk of bias in non-randomised studies of interventions. BMJ 2016;355:i4919. PMID 27733354. Version 2 (draft, November 2025 revision): https://www.riskofbias.info/welcome/robins-i-v2
  7. Higgins JPT, et al. A tool to assess risk of bias in non-randomized follow-up studies of exposure effects (ROBINS-E). Environ Int 2024;186:108602. PMID 38555664
  8. Shea BJ, et al. AMSTAR 2. BMJ 2017;358:j4008. PMID 28935701
  9. Whiting P, et al. ROBIS: a new tool to assess risk of bias in systematic reviews was developed. J Clin Epidemiol 2016;69:225-34. PMID 26092286
  10. Page MJ, et al. The PRISMA 2020 statement. BMJ 2021;372:n71. PMID 33782057
  11. Whiting PF, et al. QUADAS-3: a revised tool for the quality assessment of diagnostic test accuracy studies. Ann Intern Med 2026;179:548-55. PMID 41698208
  12. Hayden JA, et al. Assessing bias in studies of prognostic factors. Ann Intern Med 2013;158:280-6. PMID 23420236
  13. Gagnier JJ, et al. The CARE guidelines: consensus-based clinical case report guideline development. J Clin Epidemiol 2014;67:46-51. PMID 24035173
  14. Hróbjartsson A, Gøtzsche PC. Placebo interventions for all clinical conditions. Cochrane Database Syst Rev 2010;CD003974. PMID 20091554
  15. Altman DG, Bland JM. Absence of evidence is not evidence of absence. BMJ 1995;311:485. PMID 7647644
  16. Jaeschke R, Singer J, Guyatt GH. Measurement of health status: ascertaining the minimal clinically important difference. Control Clin Trials 1989;10:407-15. PMID 2691207
  17. Cohen J. Statistical Power Analysis for the Behavioral Sciences. 2nd ed. Hillsdale, NJ: Lawrence Erlbaum; 1988. Summarized in Cohen J. A power primer. Psychol Bull 1992;112:155-9 (PMID 19565683), Table 1
  18. Ciani O, et al. Comparison of treatment effect sizes associated with surrogate and final patient relevant outcomes in randomised controlled trials: meta-epidemiological study. BMJ 2013;346:f457. PMID 23360719
  19. Deeks JJ, et al. Cochrane Handbook version 6.5, 2024, chapter 10. https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-10
  20. Riley RD, et al. Interpretation of random effects meta-analyses. BMJ 2011;342:d549. PMID 21310794
  21. Egger M, et al. Bias in meta-analysis detected by a simple, graphical test. BMJ 1997;315:629-34. PMID 9310563
  22. Sterne JA, et al. Recommendations for examining and interpreting funnel plot asymmetry in meta-analyses of randomised controlled trials. BMJ 2011;343:d4002. PMID 21784880
  23. Cochrane Handbook version 6.5, 2024, chapter 13. https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-13
  24. Hill AB. The environment and disease: association or causation? Proc R Soc Med 1965;58:295-300. PMID 14283879
  25. Davey Smith G, Ebrahim S. 'Mendelian randomization': can genetic epidemiology contribute to understanding environmental determinants of disease? Int J Epidemiol 2003;32:1-22. PMID 12689998
  26. Guyatt GH, et al. GRADE guidelines: 8. Rating the quality of evidence — indirectness. J Clin Epidemiol 2011;64:1303-10. PMID 21802903
  27. Lundh A, et al. Industry sponsorship and research outcome. Cochrane Database Syst Rev 2017;MR000033. PMID 28207928
  28. Goldacre B, et al. COMPare: a prospective cohort study correcting and monitoring 58 misreported trials in real time. Trials 2019;20:118. PMID 30760329
  29. Ioannidis JPA. Why most published research findings are false. PLoS Med 2005;2:e124. PMID 16060722
  30. Brown NJL, Heathers JAJ. The GRIM test. Soc Psychol Personal Sci 2017;8:363-9. doi:10.1177/1948550616673876
med-research-setup帮助助手安装本服务器并排查故障。阅读 SKILL.md

Use when helping a user install, configure, or troubleshoot the med-research-mcp MCP server (evidence-graded multi-database literature search). Walks through registering it with an MCP client (Claude Code, Claude Desktop via .mcpb, Cursor and other JSON configs, Hermes and other YAML configs) via npx or a source build, connecting to a self-hosted HTTP instance, importing the core library directly, wiring up NCBI credentials, installing the companion skills, and verifying it works. Trigger on "install the med-research MCP", "set up med-research-mcp", "configure literature search", or connection/credential problems with it.

Installing & setting up the med-research-mcp MCP

Guide the user through this. Gather two things first, then run the right path. Don't dump every option — ask, then act.

Step 0 — Gather

Ask the user (or infer from context):

  1. Which client? Claude Code (CLI), Claude Desktop, Cursor or another JSON-config client, Hermes or another YAML-config client, a self-hosted HTTP instance, or direct library import.
  2. NCBI contact email — strongly recommended; NCBI's usage policy asks for one on every request, so NCBI can reach the user before blocking their IP. (Optional: an NCBI API key, which raises the rate limit from 3 to 10 req/s.)

Requires Node.js 22.22.2 or later on 22, 24.15.0 or later on 24, or 26+ (node --version).

Step 1 — Register with the chosen client

The package runs straight from npm with npx -y med-research-mcp; no clone or build needed. To run from a clone instead, see Step 1b.

Claude Code (CLI)

claude mcp add med-research-mcp -s user \
  -e [email protected] \
  -- npx -y med-research-mcp

Use -s user for all projects, -s local for just this one. Verify:

claude mcp get med-research-mcp      # expect: Status ✓ Connected

Tools appear in new Claude Code sessions.

Claude Desktop (.mcpb — easiest for non-technical users)

Download med-research-mcp.mcpb from the repository's latest GitHub release (or build it: npm run build:mcpb in a clone writes dist/med-research-mcp.mcpb) and drag it onto Claude Desktop. The installer offers optional fields for the NCBI contact email, an NCBI API key, an Unpaywall email and an institutional proxy prefix — no JSON editing. Note: .mcpb installs do not load the companion skills; see Step 3.

Cursor and other JSON configs (mcpServers)

{
  "mcpServers": {
    "med-research-mcp": {
      "command": "npx",
      "args": ["-y", "med-research-mcp"],
      "env": { "NCBI_EMAIL": "[email protected]" }
    }
  }
}

Hermes and other YAML configs

mcp_servers:
  med-research-mcp:
    command: npx
    args: ["-y", "med-research-mcp"]
    env:
      NCBI_EMAIL: "[email protected]"
      # optional:
      # NCBI_API_KEY: "..."

A self-hosted HTTP instance

If the user (or their team) runs the HTTP entry (npm run start:http, see docs/hosting.md in the repository), point the client at it instead:

{
  "mcpServers": {
    "med-research-mcp": {
      "type": "http",
      "url": "https://their-host/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

There is no public instance. An HTTP instance should have no institutional proxy, so its full texts come from open-access copies, free-to-read publisher pages and, for ChinaXiv/RussiaRxiv records, ChinaRxiv's machine translation.

Direct library import (any Node project)

npm install med-research-mcp, then import { searchLiterature, fetchLiterature, fetchFulltext, createCache } from "med-research-mcp/core". The build ships ESM and CommonJS, so import and require both work.

Step 1b — From a clone (development, or before a release reaches npm)

git clone https://github.com/emilkrebs/med-research-mcp.git
cd med-research-mcp
npm install
npm run build          # produces dist/

Find the absolute path (pwd) and use node <REPO>/dist/mcp/index.js as the command (args: ["<REPO>/dist/mcp/index.js"]) in any config above. Re-run npm run build after source changes, or run the source directly with npx tsx <REPO>/src/mcp/index.ts.

Step 2 — Environment reference

VarNeeded?Purpose
NCBI_EMAILrecommendedContact email NCBI's usage policy asks for, so NCBI can reach the user before blocking an IP; without it, requests carry the project's contact address. Also the fallback for the two emails below.
NCBI_API_KEYoptionalRaises the NCBI rate limit from 3 to 10 req/s
MED_RESEARCH_CHINAXIV_EMAILoptionalContact email sent to ChinaRxiv (chinaxiv, russiarxiv); raises its limit from 30 to 300 requests/minute. Falls back to NCBI_EMAIL.
MED_RESEARCH_UNPAYWALL_EMAILoptionalContact email for Unpaywall lookups (literature_fulltext). Falls back to NCBI_EMAIL, then to the project's contact address.
MED_RESEARCH_UNPAYWALLoptional0 turns the Unpaywall lookups off, so no DOI is sent there; full texts then come only from Europe PMC, ChinaRxiv, the proxy and the DOI itself.
MED_RESEARCH_PROXY_PREFIXoptionalEZproxy-style DOI prefix for off-campus full text — literature_fulltext prepends it to the DOI, e.g. https://doi-org.ezproxy.your-university.edu. Works only if the proxy lets the machine in without a login (campus network or VPN); a proxy login in the browser isn't used. Use only if the institution's licences allow it: many publishers forbid using subscription content with AI tools.
MED_RESEARCH_CACHE_BACKENDoptionalmemory (default) or sqlite (persistent, survives restarts). sqlite needs better-sqlite3, an optional native dependency; if it isn't installed or fails to load, the server warns and uses memory. .mcpb installs always use memory.
MED_RESEARCH_CACHE_PATHoptionalSQLite file path when the backend is sqlite (default ./pubmed-cache.db, relative to the directory the client starts the server in, so use an absolute path; :memory: for ephemeral).
MED_RESEARCH_FULLTEXT_MAX_CHARSoptionalThe most full-text characters returned per call. Default 50000; a longer text comes in parts (truncated: true, read on with offset: nextOffset).
MED_RESEARCH_FULLTEXT_ALLOW_PRIVATEoptional1 lets full-text fetches reach private or reserved addresses, refused by default. Only for a personal machine behind a fake-IP DNS proxy (Clash, Surge, sing-box TUN mode) or split-horizon DNS — never on a shared server.

Step 3 — Install the companion skills

So the AI actually uses the tools well, install the usage skill med-research and its critical-appraisal reference med-research-ebm (the workflow skill loads the EBM one on demand). From a clone:

mkdir -p ~/.claude/skills && cp -r <REPO>/skills/med-research <REPO>/skills/med-research-ebm ~/.claude/skills/

Without a clone, fetch them first: git clone --depth 1 https://github.com/emilkrebs/med-research-mcp.git /tmp/med-research-mcp and copy from /tmp/med-research-mcp/skills/. Use .claude/skills/ instead of ~/.claude/skills/ for a single project. Skills load in new sessions.

Claude Desktop (and claude.ai) don't read skills from a folder: zip each skill folder (med-research, med-research-ebm) and upload it under Customize → Skills → "+" → "Upload a skill". "Code execution and file creation" must be on under Settings → Capabilities.

Step 4 — Verify

Start a new session with the client and run a literature_search for creatine AND cognition[tiab] (maxResults 3). Expect a few articles with a studyType and a 0–5 designTier (null when unknown — records without NLM design metadata, and most meta-analyses).

Troubleshooting

  • npx fails or hangs → check node --version against the requirement above, and that the machine can reach the npm registry. Behind a corporate proxy, configure npm's proxy settings, or use Step 1b.
  • "No such file … dist/mcp/index.js" (clone) → run npm run build, or point the client at npx tsx <REPO>/src/mcp/index.ts instead.
  • Tools don't show up → MCP servers load at client startup; restart the session.
  • Throttling / RATE_LIMIT → the error names the database that throttled; wait retryAfter seconds. For PubMed, add NCBI_API_KEY (10 instead of 3 requests per second), and set NCBI_EMAIL so NCBI can reach the user before blocking an IP.
  • QUERY_TOO_BROAD → the query is too generic; add [tiab]/[mesh] field tags or AND clauses.
  • Full text always falls back to the abstract → the warning says what each source answered. Many papers are paywalled. If the warning says locations were refused for their addresses and the user runs a fake-IP DNS proxy (Clash, Surge, sing-box TUN mode), set MED_RESEARCH_FULLTEXT_ALLOW_PRIVATE=1 on their personal machine. Otherwise, or, where the user's institution licenses this use, configure MED_RESEARCH_PROXY_PREFIX (it works only if the proxy lets the machine in without a login, e.g. on the campus network or VPN).
  • Connection check (Claude Code): claude mcp get med-research-mcp. Remove with claude mcp remove med-research-mcp -s user.