Skip to main content
Glama

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:

Tool

Purpose

oe_auth_status

Check /api/auth/me with your cookie file

oe_history_list

Read OpenEvidence history

oe_article_get

Fetch an article by id and save artifacts

oe_ask

Ask a question, optionally wait, and save artifacts

oe_collections_list

List your collections

oe_collections_get

Get a collection (incl. nested questions[] = membership list)

oe_collections_create

Create a collection (agent-managed names should start with #)

oe_collections_add_article

Add a chat to a collection

oe_collections_db_init

Create the local SQLite mirror (idempotent)

oe_collections_sync_history

Pull /api/article/list into local SQLite chats table

oe_collections_sync_db

Refresh collections + memberships into SQLite

oe_collections_unsorted

Chats with no #-collection membership; structured JSON

oe_collections_summary

Counts + last sync timestamps

oe_collections_classify

Auto-classify unsorted chats using log-odds-ratio signatures learned from your existing memberships + curated keyword rules

oe_collections_bulk_apply

Mint missing #-collections + add memberships per [{article_id, hashtags}] plan

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:

Mode

Behavior

(default)

sync only — chats accumulate as unsorted until you run the routine

--dry-run

sync + classify; writes proposed-plan.json for review, no apply

--auto

sync + classify + bulk-apply + reconcile; fully autonomous sort

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:

File

Purpose

article.json

Full OpenEvidence article payload

answer.md

Extracted markdown answer

citations.json

Parsed structured citations

citations.bib

BibTeX bibliography

crossref-validation.json

Post-hoc Crossref validation results

Related MCP server: kjlahsdjkashdjhkasdkajshd

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.

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.

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

Target

Purpose

make deps

Run npm install

make build

Compile TypeScript

make check

Type-check

make test

Run unit tests

make smoke

Validate auth and history access

make import-cookies COOKIES=/path/to/cookies.json

Import and verify cookies

make install-claude-global

Register with Claude Code user config

make install-codex-global

Register with Codex CLI

make install-gemini-global

Register with Gemini CLI user config

make install-all

Register with Claude Code, Codex CLI, and Gemini CLI

Environment Variables

Variable

Default

Purpose

OE_MCP_BASE_URL

https://www.openevidence.com

OpenEvidence base URL

OE_MCP_ROOT_DIR

~/.openevidence-mcp

Root for default auth paths

OE_MCP_COOKIES_PATH

./cookies.json if present, else ~/.openevidence-mcp/auth/cookies.json

Cookie file

OE_MCP_AUTH_STATE_PATH

unset

Legacy alias for OE_MCP_COOKIES_PATH

OE_MCP_ARTIFACT_DIR

OS temp dir + openevidence-mcp

Artifact output directory

OE_MCP_CROSSREF_MAILTO

unset

Optional Crossref polite-pool email

OE_MCP_CROSSREF_VALIDATE

1

Set 0 to skip Crossref validation

OE_MCP_POLL_INTERVAL_MS

1200

Poll interval for oe_ask

OE_MCP_POLL_TIMEOUT_MS

180000

Default poll timeout

OE_MCP_DB_PATH

~/.openevidence-mcp/db/oe.sqlite

Local SQLite mirror used by the collections tools

OE_MCP_PYTHON

python3

Python interpreter the bridge tools spawn

Project Files

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

Available Tools

17 tools
oe_article_getOpenEvidence Article GetA

Fetch an article (answer) by id or /ask/ URL — the fetch-later half of fire-and-forget oe_ask. Returns the current status; if it is still 'pending' either retry later or pass wait_for_completion:true to block until the answer is ready. Completed answers are served from the local SQLite store when available (from_cache:true, zero network) — pass refresh:true to force a re-fetch from OpenEvidence.

Inputs: article_id (required), refresh, timeout_sec, include_bibtex, +5 more.

oe_article_set_accessOpenEvidence Article Share AccessA

Set a conversation's share visibility (PATCH /api/article//access). public:true makes it link-shareable (ANYONE_WITH_LINK — anyone with the URL can read it, no login); public:false makes it private again (CREATOR_ONLY). Returns the shareable /ask/ URL. You must own the conversation, and the relay extension must be connected (only the owning browser session may change access). ⚠️ Publishing exposes the conversation to anyone on the internet with the link — do not publish anything containing PHI or medically sensitive patient information.

Inputs: public (required), article_id (required).

oe_askOpenEvidence AskA

Create a question. Fire-and-forget by default: returns {article_id, status:'pending'} immediately so the browser tab is free for other sessions — fetch the finished answer later with oe_article_get (optionally wait_for_completion:true). Pass wait_for_completion:true here to block and return the answer in one call. For a follow-up question pass original_article_id. Submits POST /api/article through the connected browser-extension relay (runs in your real logged-in tab, DataDome-free); the direct Node POST is deprecated and no longer attempted. Requires the relay extension to be connected (see extension/README.md).

Inputs: question (required), timeout_sec, article_type, include_bibtex, +9 more.

oe_auth_statusOpenEvidence Auth StatusA

Check if the local OpenEvidence session is valid (full network round-trip). For a fast pipeline-connectivity check use oe_health instead.

Inputs: no named parameters.

oe_collections_add_articleOpenEvidence Collection Add ArticleC

Add a chat (article) to a collection. Idempotent in practice.

Inputs: article_id (required), collection_id (required).

oe_collections_createOpenEvidence Collection CreateB

Create a new collection. By convention, agent-managed names start with '#'.

Inputs: name (required), description.

oe_collections_db_initInit Collections SQLite MirrorA

Create the local SQLite mirror at $OE_MCP_DB_PATH (default ~/.openevidence-mcp/db/oe.sqlite). Idempotent.

Inputs: no named parameters.

oe_collections_getOpenEvidence Collection GetA

Fetch a collection (incl. nested questions[] = membership list) by id.

Inputs: collection_id (required).

oe_collections_listOpenEvidence Collections ListA

List all collections owned by the authenticated user.

Inputs: no named parameters.

oe_collections_summaryCollections SummaryB

Counts (chats, collections, hashtag, memberships, unsorted) + last sync timestamps.

Inputs: no named parameters.

oe_collections_sync_dbSync Collections + Memberships to SQLiteB

Refresh collections and memberships from the API into local SQLite. Prunes collections + memberships the server no longer reports.

Inputs: rate_seconds.

oe_collections_sync_historySync Chat History to SQLiteA

Paginate /api/article/list and upsert chats. Incremental by default (stops on the first all-known page).

Inputs: full, pages, page_size, rate_seconds.

oe_collections_unsortedList Unsorted ChatsA

Chats with no membership in any '#'-prefixed collection. Returns {unsorted_count, shown, items[]}.

Inputs: limit, preview_chars.

oe_healthOpenEvidence Relay HealthA

Millisecond-fast local check of the relay pipeline (daemon + browser extension) — no OpenEvidence network call. Use this to confirm the pipeline is up before oe_ask; use oe_auth_status only when you need to verify the login session itself.

Inputs: no named parameters.

oe_history_listOpenEvidence History ListC

List question history from OpenEvidence account.

Inputs: limit, offset, search.

oe_public_getOpenEvidence Conversation Page GetA

Read an OpenEvidence conversation from an /ask/ link and parse the page into Q&A turns (question, answer as markdown, references). Public (shared) conversations need no setup at all; your own private ones work when the relay extension is connected (your logged-in tab) or cookies.json exists. Use oe_article_get when you want the raw API payload + saved artifacts instead.

Inputs: url (required), strip_citation_markers.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose, with descriptions that eliminate ambiguity. For example, oe_health vs oe_auth_status differentiate between local pipeline check and session verification, and oe_collections tools each handle a specific aspect of collection management.

    Naming Consistency4/5

    Tools follow a consistent pattern of 'oe_' prefix followed by a domain (collections, article, auth, etc.) and then a verb or noun. While not strictly verb_noun throughout (e.g., oe_health, oe_collections_summary), the pattern is predictable and readable.

    Tool Count5/5

    17 tools is well-scoped for the OpenEvidence domain, covering authentication, health checks, collections management (9 tools), article operations, and search. Each tool serves a specific need without unnecessary duplication.

    Completeness4/5

    The tool surface covers the core workflows: asking questions, retrieving answers, searching, managing collections, and setting access. Minor gaps exist, such as no explicit delete tool for articles, but overall the set is comprehensive for its purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers