OpenEvidence MCP (Unofficial)

OpenEvidence MCP is an unofficial Model Context Protocol server that connects OpenEvidence to Codex, Claude Code, Claude Desktop, 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.

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

Agent Onboarding & Installation

Using Codex, Claude Code, Cursor, or another local AI coding agent? You can let the agent handle the entire setup, compilation, and local MCP configuration for you!

Copy and paste this short bootstrap prompt directly into your local AI coding assistant:

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.

For the comprehensive, step-by-step setup playbook and rules, see docs/AGENT_INSTALL_PROMPT.md.

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;
• polling an existing OpenEvidence article until it completes.

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 requests from your machine.
• 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.

Tested / Target Clients

This project is designed for MCP-compatible clients and local agent workflows. Only Codex and Claude-style local configuration examples are maintained in this repository unless otherwise noted.

Other MCP-compatible hosts may work as well, but the examples in this repository focus on Codex and Claude-style local MCP configuration.

Features

Agent Tool-Calling Notes

The MCP server includes built-in instructions and a prompt named openevidence_research_workflow for clients that expose MCP prompts.

Recommended agent workflow:

1. Call oe_auth_status when auth state is unknown.
2. Use oe_history_list only when the user wants prior OpenEvidence work or an article ID.
3. Use oe_article_get when you already have an article ID.
4. For long research questions, call oe_ask with wait_for_completion=false, then call oe_article_wait with the returned article_id.
5. Use original_article_id only for true follow-up continuity. Omit it for fresh questions to avoid stale thread context.
6. Treat outputs as evidence-research context, not medical advice, diagnosis, or clinical orders.

Related commands:

Requirements

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

Availability Note

OpenEvidence availability may depend on region, account eligibility, and OpenEvidence policy. Public materials in May 2026 indicate verified U.S. HCP/NPI-centered access and EU/U.K. unavailability; this project does not bypass those restrictions.

Useful references:

• OpenEvidence homepage
• OpenEvidence API/product page
• OpenEvidence Privacy Policy

Quick Start

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

Login Flow

Recommended one-time login:

npm run login:session

The command opens Chrome or Edge with a local OpenEvidence MCP browser profile. Sign in to OpenEvidence with your own account, confirm the normal OpenEvidence page loads, close that browser window, return to the terminal, and press Enter.

Default local profile path:

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

The MCP server reuses this same local profile during its process lifetime. It may start a minimized local browser process for OpenEvidence calls, but it does not install an extension, expose a public network service, export cookies, or ask for your password.

Legacy/development flow:

npm run login

If Google sign-in says the browser or app may not be secure during the legacy flow, use the session login instead:

npm run login:session

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

MCP Client Setup

Build before registering the server:

npm run build

Automatic Setup (Recommended)

You can automatically register the OpenEvidence MCP server with your favorite client using the built-in installer: