OpenEvidence MCP

OpenEvidence MCP（非官方）

无需 API 密钥。使用 npm run login:session 登录一次即可；服务会重复使用你的本地浏览器配置文件。注册表元数据版本 0.2.2 继续使用现有的 npm 软件包 0.2.1。

OpenEvidence MCP 是一款非官方的 Model Context Protocol 服务，可通过你自己的已认证浏览器会话，将 OpenEvidence 连接到 Codex、Claude Code、Claude Desktop、Cursor、Cline、Continue 及其他兼容 MCP 的客户端。

重要

本项目为非官方项目，与 OpenEvidence 没有关联。它不提供医疗建议，不绕过访问控制，且仅可在遵守适用条款、隐私规则和临床治理要求的前提下，使用你自己的 OpenEvidence 账户。

翻译：Русский | Español | 简体中文 | 繁體中文（台灣） | 한국어 | हिन्दी

Agent 入门与安装

正在使用 Codex、Claude Code、Cursor 或其他本地 AI 编码 Agent？你可以让 Agent 为你处理整个设置、编译和本地 MCP 配置过程！

将以下简短的引导提示词复制并粘贴到你的本地 AI 编码助手中：

Please install OpenEvidence MCP for me: clone https://github.com/bakhtiersizhaev/openevidence-mcp, install dependencies, run build, auto-configure this MCP server in my local client (Claude Desktop/Codex/Cursor), guide me through the one-time Edge/Chrome login using `npm run login:session`, and run `npm run smoke` to verify. Keep everything strictly local and secure.

如需全面的分步设置指南和规则，请参阅 docs/AGENT_INSTALL_PROMPT.md。

功能

OpenEvidence MCP 会运行一个本地 stdio MCP 服务，让 MCP 客户端使用你现有的 OpenEvidence 浏览器会话来：

• 检查已保存的会话是否通过身份验证；
• 列出你的 OpenEvidence 问题／文章历史记录；
• 按 ID 获取完整的文章载荷；
• 提出 OpenEvidence 研究问题，并可选择等待完成；
• 轮询已有的 OpenEvidence 文章，直到其处理完成。

无需官方 OpenEvidence API 令牌。

不具备的功能

• 它与 OpenEvidence 没有关联，也未获其认可或批准。
• 它不提供医疗建议，也不替代临床判断。
• 它不绕过身份验证、付费墙或访问控制。
• 它不收集凭据。
• 除了从你的设备发出的本地请求外，它不会将你的浏览器会话状态发送到任何地方。
• 未经适当的人工审核，不应将其用于针对特定患者的诊断或治疗决策。

适用人群

• 使用自己 OpenEvidence 账户的临床医生；
• 医学研究人员；
• 构建循证研究工作流的 AI 操作人员；
• 将本地工具集成到 Codex、Claude、Cursor、Cline、Continue 或类似客户端中的 MCP 开发者。

已测试 / 目标客户端

本项目面向兼容 MCP 的客户端和本地 Agent 工作流。除非另有说明，本仓库仅维护 Codex 和 Claude 风格的本地配置示例。

客户端	状态	备注
OpenAI Codex / Codex CLI / Codex app	目标	推荐的本地 MCP 工作流。
Claude Code	目标	推荐的 Agent 工作流。
Claude Desktop / 支持 MCP 的 Claude app	目标	本地 MCP 服务配置。
Cursor	兼容	兼容 MCP 的 IDE 工作流。
Cline	兼容	VS Code Agent 工作流。
Continue	兼容	开源 IDE 助手工作流。
支持 MCP 的 VS Code / GitHub Copilot 环境	实验性	取决于本地 MCP 支持情况和客户端配置。
Windsurf / Zed / Replit / Sourcegraph 风格的 MCP 主机	实验性	未经测试时不保证可用。
Gemini CLI / Google Antigravity 风格的 Agent 环境	实验性	关注列表 / 生态目标，并非维护中的示例。

其他兼容 MCP 的主机也可能可用，但本仓库中的示例主要针对 Codex 和 Claude 风格的本地 MCP 配置。

功能

工具	用途	是否需要身份验证	副作用
oe_auth_status	检查已保存的 OpenEvidence 浏览器会话是否已通过身份验证。	是，本地浏览器配置文件必须已登录。	无。
oe_history_list	列出此前的 OpenEvidence 文章，支持可选的分页和搜索。除非明确请求 include_raw=true，否则返回经过隐私精简的列表。	是。	无。
oe_article_get	按 ID 获取文章，并返回规范化字段（status、is_complete、question、answer_text）。原始数据需通过 include_raw=true 显式选择。	是。	无。
oe_article_wait	等待已有文章 ID 对应的文章完成；适用于非阻塞式 oe_ask 之后。	是。	无。
oe_ask	创建 OpenEvidence 研究问题，并可选择等待文章完成。	是。	在你的 OpenEvidence 账户中创建问题 / 文章。

Agent 工具调用说明

MCP 服务内置了指令，以及一个名为 openevidence_research_workflow 的提示词，供支持 MCP 提示词的客户端使用。

推荐的 Agent 工作流：

1. 身份验证状态未知时，调用 oe_auth_status。
2. 仅当用户需要查看此前的 OpenEvidence 工作或提供了文章 ID 时，才使用 oe_history_list。
3. 已有文章 ID 时，使用 oe_article_get。
4. 对于较长的研究问题，调用 oe_ask 并设置 wait_for_completion=false，然后使用返回的 article_id 调用 oe_article_wait。
5. 仅在确实需要延续上下文时使用 original_article_id。对于新问题，请省略此参数，以避免使用过时的线程上下文。
6. 将输出视为证据研究上下文，而非医疗建议、诊断或临床医嘱。

相关命令：

命令	用途
npm run login:session	推荐的一次性登录方式。使用本地 OpenEvidence MCP 配置文件打开 Chrome/Edge。
npm run login	旧版 / 开发用 Playwright 登录流程，同样使用本地配置文件。
npm run login:browser	用于调试 Google SSO 问题的旧版系统浏览器登录 / 导出流程。
npm run smoke	验证身份验证状态和 OpenEvidence 基本连通性。

要求

• Node.js 20+
• npm 10+
• OpenEvidence 账户
• macOS、Windows 或 Linux
• 由 Playwright 安装的 Chromium（npx playwright install chromium）

可用性说明

OpenEvidence 的可用性可能取决于地区、账户资格和 OpenEvidence 政策。2026 年 5 月的公开资料表明，已验证的访问以美国 HCP/NPI 为中心，且欧盟 / 英国不可用；本项目不会绕过这些限制。

有用的参考资料：

• OpenEvidence 主页
• OpenEvidence API / 产品页面
• OpenEvidence 隐私政策

快速入门

macOS

git clone https://github.com/bakhtiersizhaev/openevidence-mcp.git
cd openevidence-mcp
./scripts/setup-macos.sh
npm run login:session
npm run smoke

Ubuntu/Linux

git clone https://github.com/bakhtiersizhaev/openevidence-mcp.git
cd openevidence-mcp
./scripts/setup-ubuntu.sh
npm run login:session
npm run smoke

Windows PowerShell

git clone https://github.com/bakhtiersizhaev/openevidence-mcp.git
cd openevidence-mcp
.\scripts\setup-windows.ps1
npm run login:session
npm run smoke

登录流程

建议进行一次性登录：

npm run login:session

该命令会打开 Chrome 或 Edge，并使用本地 OpenEvidence MCP 浏览器配置文件。使用你自己的账户登录 OpenEvidence，确认 OpenEvidence 页面正常加载，然后关闭该浏览器窗口，返回终端并按 Enter。

默认本地配置文件路径：

• macOS/Linux：~/.openevidence-mcp/browser-profile
• Windows：%USERPROFILE%\.openevidence-mcp\browser-profile

MCP 服务会在其进程运行期间重复使用此本地配置文件。调用 OpenEvidence 时，它可能会启动一个最小化的本地浏览器进程，但不会安装扩展程序、公开网络服务、导出 Cookie，也不会索要你的密码。

旧版/开发流程：

npm run login

如果在旧版流程中使用 Google 登录时提示浏览器或应用可能不安全，请改用会话登录：

npm run login:session

请勿分享浏览器配置文件、存储状态文件、Cookie、包含账户隐私数据的屏幕截图或可识别患者身份的信息。

MCP 客户端设置

注册服务之前先进行构建：

npm run build

自动设置（推荐）

你可以使用内置安装程序，自动将 OpenEvidence MCP 服务注册到你常用的客户端：

• Claude Desktop（claude-app）：

  npx openevidence-mcp install --client claude-app
  # or via npm shortcut:
  npm run install:claude-app
  

• Codex Desktop（codex-app）：

  npx openevidence-mcp install --client codex-app
  # or via npm shortcut:
  npm run install:codex-app
  

• Claude Code（claude-code）：

  npx openevidence-mcp install --client claude-code
  # or via npm shortcut:
  npm run install:claude-code
  

• Codex CLI（codex-cli）：

  npx openevidence-mcp install --client codex-cli
  # or via npm shortcut:
  npm run install:codex-cli
  

• Google Antigravity（antigravity）：

  npx openevidence-mcp install --client antigravity
  # or via npm shortcut:
  npm run install:antigravity
  

• Cursor（cursor）：

  npx openevidence-mcp install --client cursor
  # or via npm shortcut:
  npm run install:cursor
  

• Windsurf（windsurf）：

  npx openevidence-mcp install --client windsurf
  # or via npm shortcut:
  npm run install:windsurf
  

要卸载，可以运行：

npx openevidence-mcp uninstall --client <client-id>

---

手动设置

Codex

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.openevidence]
command = "node"
args = ["/ABSOLUTE/PATH/openevidence-mcp/dist/server.js"]
startup_timeout_sec = 60

Windows 示例：

[mcp_servers.openevidence]
command = "node"
args = ["C:\\Users\\<user>\\openevidence-mcp\\dist\\server.js"]
startup_timeout_sec = 60

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "openevidence": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/openevidence-mcp/dist/server.js"]
    }
  }
}

Cursor、Cline、Continue

如果客户端支持 MCP 服务命令/参数配置，请使用相同的 stdio 服务格式：

{
  "command": "node",
  "args": ["/ABSOLUTE/PATH/openevidence-mcp/dist/server.js"]
}

示例配置位于 examples/ 中。

验证

npm run smoke

会话有效时的预期结果：

• ok: true
• authenticated: true
• 经过脱敏的历史记录预览

如果 smoke 因身份验证错误而失败，请重新运行 npm run login:session。Smoke 需要真实的 OpenEvidence 账户会话；如果没有可用的本地会话配置文件，则无法在干净的 CI 环境中通过。

默认情况下，smoke 输出会对账户和历史记录内容进行脱敏。只有在私密终端中确实需要原始账户/历史记录负载进行调试时，才使用 npm run smoke -- --verbose。

开发者检查：

npm test
npm run build
npm run check

安全说明

• 请将浏览器配置文件、storage-state.json 和 Cookie 视为机密信息。
• 请勿提交 .env、会话状态、包含账户数据的屏幕截图或可识别患者身份的信息。
• 仅使用你自己的 OpenEvidence 账户。
• 确保 MCP 客户端配置指向你控制的本地构建服务路径。
• 在临床或运营工作流中使用自主 Agent 的输出前，请先检查其工具调用。
• 有关漏洞报告和支持范围，请参阅 SECURITY.md。

故障排除

详细的恢复步骤请参阅 docs/TROUBLESHOOTING.md。

常见解决方法：

• authenticated: false：重新运行 npm run login:session。
• 在旧版登录流程中，Google 提示浏览器不安全：运行 npm run login:session。
• 浏览器安装错误：运行 npx playwright install chromium。
• MCP 客户端无法启动服务：确认 npm run build 已成功，并使用 dist/server.js 的绝对路径。
• Windows 路径问题：在 JSON/TOML 中转义反斜杠，或使用完整绝对路径。
• Node 错误：确认 node --version 为 20 或更高版本。
• OpenEvidence UI/API 已更改：提交 issue，并附上经过脱敏的日志，不要包含账户隐私数据或患者数据。
• oe_ask 无法找到问题输入框或提交按钮：OpenEvidence UI 可能已更改；请提交 issue，并附上经过脱敏的日志，不要包含账户隐私数据或患者数据。

路线图

• 保持工具描述简洁，并便于 Agent 使用。
• 围绕配置和响应解析添加针对性测试。
• 改进冒烟测试诊断，同时避免暴露会话详情。
• 随着客户端配置格式的演进，跟踪 MCP 客户端设置示例。

许可证与署名

Apache-2.0（LICENSE）+ NOTICE。

如果你重新分发、分叉或构建衍生版本，请保留以下署名：

• 原作者：Bakhtier Sizhaev
• 原始仓库：https://github.com/bakhtiersizhaev/openevidence-mcp

建议的署名行：

Based on OpenEvidence MCP by Bakhtier Sizhaev - https://github.com/bakhtiersizhaev/openevidence-mcp

Star 历史