:
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 |
| Check |
| Read OpenEvidence history |
| Fetch an article by id and save artifacts |
| Ask a question, optionally wait, and save artifacts |
| List your collections |
| Get a collection (incl. nested questions[] = membership list) |
| Create a collection (agent-managed names should start with |
| Add a chat to a collection |
| Create the local SQLite mirror (idempotent) |
| Pull /api/article/list into local SQLite chats table |
| Refresh collections + memberships into SQLite |
| Chats with no |
| Counts + last sync timestamps |
| Auto-classify unsorted chats using log-odds-ratio signatures learned from your existing memberships + curated keyword rules |
| Mint missing |
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 summarySchedule 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 # removeThe 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 |
| sync + classify; writes |
| 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 |
| Full OpenEvidence article payload |
| Extracted markdown answer |
| Parsed structured citations |
| BibTeX bibliography |
| 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 buildExport 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 smokeThe 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 openevidenceWhat it registers:
node /ABSOLUTE/PATH/openevidence-mcp/dist/server.js
OE_MCP_COOKIES_PATH=/ABSOLUTE/PATH/openevidence-mcp/cookies.jsonCodex CLI
make install-codex-global
codex mcp get openevidenceEquivalent 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 listEquivalent 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-allThis 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 smokeExpected 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_idextracted answer markdown as
extracted_answer_rawartifact file paths
inline BibTeX as
artifacts.bibtexsaved 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.jsonCrossref validation behavior:
DOI citations are validated directly with Crossref.
Non-DOI citations use a bibliographic query and are marked as
candidate,not_found, orerror.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 loginThen restart or open a fresh MCP client session if the old stdio server process is still alive.
Make Targets
Target | Purpose |
| Run |
| Compile TypeScript |
| Type-check |
| Run unit tests |
| Validate auth and history access |
| Import and verify cookies |
| Register with Claude Code user config |
| Register with Codex CLI |
| Register with Gemini CLI user config |
| Register with Claude Code, Codex CLI, and Gemini CLI |
Environment Variables
Variable | Default | Purpose |
|
| OpenEvidence base URL |
|
| Root for default auth paths |
|
| Cookie file |
| unset | Legacy alias for |
| OS temp dir + | Artifact output directory |
| unset | Optional Crossref polite-pool email |
|
| Set |
|
| Poll interval for |
|
| Default poll timeout |
|
| Local SQLite mirror used by the collections tools |
|
| Python interpreter the bridge tools spawn |
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
Available Tools
17 toolsoe_answers_searchSearch Stored Answers (local FTS)A
Full-text search (SQLite FTS5) over every answer previously fetched by oe_ask/oe_article_get — questions, titles, and answer bodies. Millisecond-fast and fully offline: no OpenEvidence traffic, no rate-limit cost. Covers only answers this MCP has fetched and stored locally; for your complete server-side history use oe_history_list. Snippets mark matches with »…«.
Inputs: query (required), limit.
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Generate, edit, and explore AI images. Flux, Imagen, LoRA identity swap, upscale, and more.
Licensed soundtracks and sound effects matched to your video. Commercial use OK.
Human-made production music for sync. Search by brief or reference, preview, and score to picture.
Sold comps and active listings from eBay, Poshmark, Mercari, Depop, Vinted, TCGplayer and more.
Related MCP Servers
- -
- -
- -
- ISC