Htlin222 Openevidence

What It Does

This is an unofficial OpenEvidence MCP server that reuses cookies exported from your own logged-in OpenEvidence browser session. It does not launch a browser, does not install Playwright, and does not need an official OpenEvidence API key.

It is designed for local personal workflows where you already have lawful access to OpenEvidence. It does not bypass authentication, remove access controls, redistribute OpenEvidence content, or include OpenEvidence data in this repository.

Tools:

oe_ask and oe_article_get return BibTeX in the MCP response by default when artifacts are saved. Pass include_bibtex: false to keep the response smaller while still writing citations.bib to disk.

Saved artifacts:

Fast Install

git clone https://github.com/htlin222/openevidence-mcp.git
cd openevidence-mcp
npm install
npm run build

Export cookies from a logged-in https://www.openevidence.com browser session and put them here:

cp /path/to/browser-cookies.json ./cookies.json
npm run login
npm run smoke

The cookie file can be a browser-exported cookies array or a storage-state object with a cookies array.

Register With MCP Clients

Use one of these.

Claude Code

make install-claude-global
claude mcp get openevidence

What it registers:

node /ABSOLUTE/PATH/openevidence-mcp/dist/server.js
OE_MCP_COOKIES_PATH=/ABSOLUTE/PATH/openevidence-mcp/cookies.json

Codex CLI

make install-codex-global
codex mcp get openevidence

Equivalent manual command:

codex mcp add openevidence \
  --env OE_MCP_COOKIES_PATH="$PWD/cookies.json" \
  -- node "$PWD/dist/server.js"

Manual ~/.codex/config.toml:

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

[mcp_servers.openevidence.env]
OE_MCP_COOKIES_PATH = "/ABSOLUTE/PATH/openevidence-mcp/cookies.json"

Gemini CLI

make install-gemini-global
gemini mcp list

Equivalent manual command:

gemini mcp add --scope user \
  -e OE_MCP_COOKIES_PATH="$PWD/cookies.json" \
  openevidence node "$PWD/dist/server.js"

Claude Desktop, Cursor, Cline, Continue

Use this mcpServers shape:

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

Install Everywhere

make install-all

This registers the same local stdio server with Claude Code, Codex CLI, and Gemini CLI.

Verify

npm run check
npm test
npm run build
npm run smoke

Expected smoke result:

{
  "ok": true,
  "authenticated": true
}

MCP stdio servers normally start on demand when the client checks or uses them. They do not need to run as a separate daemon.

How To Ask Questions

After registration, ask your MCP client in plain English and mention OpenEvidence. The agent should call oe_ask automatically.

Example prompts:

Use OpenEvidence to answer: DLBCL frontline treatment landscape NCCN v3.2026. Include citations and BibTeX.

Use OpenEvidence to compare Pola-R-CHP vs R-CHOP in untreated DLBCL. Include trial citations and BibTeX.

Use OpenEvidence to review current evidence for SGLT2 inhibitors in HFpEF. Include citations and BibTeX.

Use OpenEvidence to find guideline-supported anticoagulation options for cancer-associated thrombosis.

The underlying MCP call looks like this:

{
  "tool": "oe_ask",
  "arguments": {
    "question": "DLBCL frontline treatment landscape NCCN v3.2026",
    "wait_for_completion": true,
    "include_bibtex": true
  }
}

oe_ask returns:

• the OpenEvidence article payload
• article_id
• extracted answer markdown as extracted_answer_raw
• artifact file paths
• inline BibTeX as artifacts.bibtex
• saved citation files under the artifact directory

To fetch BibTeX for a prior answer, ask:

Use OpenEvidence to fetch article <ARTICLE_ID> and show the BibTeX.

That maps to oe_article_get:

{
  "article_id": "<ARTICLE_ID>",
  "include_bibtex": true
}

If the response is too large, use include_bibtex: false; the server will still write citations.bib to disk.

Citation Artifacts

Completed oe_ask and oe_article_get calls save artifacts under:

/tmp/openevidence-mcp/<article_id>/

On macOS, Node may resolve /tmp to a path under /var/folders/.../T/.

Example output:

answer.md
article.json
citations.json
citations.bib
crossref-validation.json

Crossref validation behavior:

• DOI citations are validated directly with Crossref.
• Non-DOI citations use a bibliographic query and are marked as candidate, not_found, or error.
• Low-similarity Crossref matches are not used to overwrite BibTeX metadata.
• Sources like NCCN guidelines may stay as local OpenEvidence metadata because Crossref often has no authoritative match.

Copyright, Trademark, And Medical Disclaimer

This project is unofficial and independent. It is not affiliated with, endorsed by, sponsored by, or approved by OpenEvidence or its owners. "OpenEvidence" and related names, logos, product names, and content remain the property of their respective owners.

This repository contains connector code only. It does not include OpenEvidence copyrighted content, proprietary datasets, model outputs, article payloads, session cookies, or account material. Your local use of this MCP server may create files such as answer.md, article.json, and citations.bib; those artifacts can contain content retrieved from or derived from your OpenEvidence account session. Treat those files as private unless you have the right to share them.

You are responsible for complying with OpenEvidence terms, institutional policies, copyright law, and any clinical data governance rules that apply to your use. Do not publish cookies, account tokens, saved article payloads, generated answers, screenshots, guideline text, or other protected/copyrighted content unless you have permission or another valid legal basis.

This software is not medical advice and is not a medical device. It is an integration tool for an MCP client. Clinicians and qualified users remain responsible for verifying outputs against authoritative sources and applying independent clinical judgment.

Cookie Refresh

If auth stops working:

cp /path/to/fresh-browser-cookies.json ./cookies.json
npm run login

Then restart or open a fresh MCP client session if the old stdio server process is still alive.

Make Targets

Environment Variables

Project Files

• README.AI.md - agent install playbook
• examples/codex-config.toml - Codex MCP config
• examples/claude-desktop-config.json - JSON MCP config
• src/citations.ts - citation extraction, BibTeX, Crossref validation
• src/cookies.ts - cookie file parsing
• src/server.ts - MCP tools
• test/citations.test.ts - unit tests

License And Attribution

Apache-2.0. Keep LICENSE and NOTICE when redistributing.

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