OpenEvidence MCP (Unofficial)

OpenEvidence MCP is an unofficial Model Context Protocol server that connects OpenEvidence to Codex, Claude, Cursor, Cline, Continue, and other MCP-compatible clients through your own authenticated browser session.

[!IMPORTANT]
This project is unofficial and is not affiliated with OpenEvidence. It does not provide medical advice, does not bypass access controls, and should only be used with your own OpenEvidence account in compliance with applicable terms, privacy rules, and clinical governance requirements.

What it does

OpenEvidence MCP runs a local stdio MCP server that lets MCP clients use your existing OpenEvidence browser session for:

• checking whether the saved session is authenticated;
• listing your OpenEvidence question/article history;
• fetching a full article payload by ID;
• asking an OpenEvidence research question and optionally waiting for completion.

No official OpenEvidence API token is required.

What it does NOT do

• It is not affiliated with, endorsed by, or approved by OpenEvidence.
• It does not provide medical advice or replace clinical judgment.
• It does not bypass authentication, paywalls, or access controls.
• It does not collect credentials.
• It does not send your browser session state anywhere except to OpenEvidence through local Playwright requests.
• It should not be used for patient-specific diagnosis or treatment decisions without appropriate human review.

Who it is for

• clinicians using their own OpenEvidence account;
• medical researchers;
• AI operators building evidence-research workflows;
• MCP developers integrating local tools with Codex, Claude, Cursor, Cline, Continue, or similar clients.

Features

Related commands:

Requirements

• Node.js 20+
• npm 10+
• OpenEvidence account
• macOS, Windows, or Linux
• Chromium installed by Playwright (npx playwright install chromium)

Quick Start

macOS

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

Ubuntu/Linux

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

Windows PowerShell

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

Login Flow

Run:

npm run login

The command opens a browser window. Sign in to OpenEvidence with your own account, return to the terminal, and press Enter. The login script validates /api/auth/me and saves local browser session state.

Default state paths:

• macOS/Linux: ~/.openevidence-mcp/auth/storage-state.json
• Windows: %USERPROFILE%\.openevidence-mcp\auth\storage-state.json

You can import an existing Playwright storage state file:

npm run login -- --import /absolute/path/storage-state.json

Do not share storage-state files, cookies, screenshots with private account data, or patient-identifiable information.

MCP Client Setup

Build before registering the server:

npm run build

Codex

Add this to ~/.codex/config.toml:

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

Windows example:

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

Claude Desktop

Add this to claude_desktop_config.json:

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

Cursor, Cline, Continue

Use the same stdio server shape if your client supports MCP server command/args configuration:

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

Example configs are in examples/.

Verify

npm run smoke

Expected result with a valid session:

• ok: true
• authenticated: true
• a small history preview

If smoke fails with an auth error, run npm run login again. Smoke requires a real OpenEvidence account session and will not pass in a clean CI environment unless session state is provided securely.

Security Notes

• Treat storage-state.json, cookies, and browser profiles as secrets.
• Do not commit .env, session state, screenshots with account data, or patient-identifiable information.
• Use only your own OpenEvidence account.
• Keep MCP client configs pointed at the built local server path you control.
• Review tool calls from autonomous agents before using outputs in clinical or operational workflows.
• See SECURITY.md for vulnerability reporting and supported scope.

Troubleshooting

See docs/TROUBLESHOOTING.md for detailed recovery steps.

Common fixes:

• authenticated: false: rerun npm run login.
• Browser install errors: run npx playwright install chromium.
• MCP client cannot start server: confirm npm run build succeeded and use an absolute path to dist/server.js.
• Windows path issues: escape backslashes in JSON/TOML or use full absolute paths.
• Node errors: confirm node --version is 20 or newer.
• OpenEvidence UI/API changed: open an issue with sanitized logs and no private account or patient data.

Roadmap

• Keep tool descriptions compact and agent-friendly.
• Add focused tests around config and response parsing.
• Improve smoke diagnostics without exposing session details.
• Track MCP client setup examples as client configuration formats evolve.

License & Attribution

Apache-2.0 (LICENSE) + NOTICE.

If you redistribute, fork, or build derivative versions, keep attribution to:

• Original author: Bakhtier Sizhaev
• Original repository: https://github.com/bakhtiersizhaev/openevidence-mcp

Suggested attribution line:

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