:

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.

Collections sync & auto-sort routine

scripts/collection_sort.py mirrors your chat history and collection memberships into a local SQLite (~/.openevidence-mcp/db/oe.sqlite by default; override with OE_MCP_DB_PATH). The companion routine routines/collection-sort.md walks an MCP client through syncing, surfacing unsorted chats, and applying multi-membership hashtag tags. The convention: collections whose name starts with # are agent-managed; collections without a leading hash are human-curated and the routine never touches them.

The same pipeline is exposed as MCP tools (oe_collections_db_init, oe_collections_sync_history, oe_collections_sync_db, oe_collections_unsorted, oe_collections_summary, oe_collections_bulk_apply) — the TS server shells out to scripts/collection_sort.py via python3 (override with OE_MCP_PYTHON) so the DataDome-safe HTTP path stays canonical.

python scripts/collection_sort.py init
python scripts/collection_sort.py sync-history --full   # first time
python scripts/collection_sort.py sync-collections
python scripts/collection_sort.py list-unsorted --json  # routine reads this
python scripts/collection_sort.py summary

Schedule the sync (macOS)

The classification step needs the agent in the loop, but the sync side is pure I/O — install a daily launchd job that keeps the local SQLite mirror fresh so the next agent run has zero lag:

bash scripts/install_launchd.sh                  # daily 02:00 (override via OE_MCP_SYNC_HOUR / OE_MCP_SYNC_MINUTE)
launchctl start com.htlin.openevidence-mcp.sync  # fire once now to verify
tail -30 ~/.openevidence-mcp/logs/sync.log
bash scripts/install_launchd.sh --uninstall      # remove

The wrapper (scripts/collection_sync_cron.sh) appends one block per run to ~/.openevidence-mcp/logs/sync.log containing the sync-history / sync-collections / summary output. Override the log dir with OE_MCP_LOG_DIR.

The wrapper takes an optional mode flag:

scripts/classify.py runs offline, no API. It builds a per-tag log-odds-ratio signature (Monroe et al. 2008) from your existing memberships every run, OR'd with curated keyword rules. Validate quality on your data with python scripts/classify.py validate (held-out cross-validation; on the first 603 memberships I verified, hit-rate = 99.4% with recall ≈1.0; precision varies by tag — raise --threshold for tighter precision in --auto mode). Tune for headless use via OE_MCP_AUTO_THRESHOLD (default 12) and OE_MCP_AUTO_TOP_K (default 3). Switch the launchd job to autonomous mode with OE_MCP_SYNC_MODE=--auto bash scripts/install_launchd.sh.

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"

Antigravity CLI (agy-cli)

make install-agy-global
agy-cli mcp list

Equivalent manual command:

agy-cli 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 Antigravity 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