Skip to content
Back to search

openevidence-mcp

Unofficial OpenEvidence MCP server — query OpenEvidence from Claude Code, Codex, and any MCP client through your own logged-in browser tab (no API key). Fire-and-forget asks, a shared relay daemon for concurrent sessions, BibTeX + Crossref citations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/htlin222/openevidence-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/htlin222/openevidence-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/htlin222--openevidence-mcp/badge.svg)](/listings/htlin222--openevidence-mcp)

HTML

<a href="/listings/htlin222--openevidence-mcp"><img src="/api/listings/htlin222--openevidence-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/htlin222/openevidence-mcp.git
cd openevidence-mcp
make all      # installs deps · builds the MCP server + relay extension ·
              # registers the server into Claude and Codex (whichever CLI you have)

Then the one manual step `make all` prints (a browser action that can't be scripted):

1. **Load the extension** — open `chrome://extensions` (Chrome / Edge / Brave / Arc / Vivaldi / Opera) → turn on **Developer mode** → **Load unpacked** → select `extension/dist`. 2. **Stay logged in to [openevidence.com](https://www.openevidence.com)** in that browser, and keep a tab open. That login *is* your authentication. 3. **Run your AI tool.** The server auto-starts the relay and connects to the extension.

Verify and go:

curl -s http://127.0.0.1:8787/health     # expect {"ok":true,"connected":true,"version":1,...}

Then just ask, in any MCP client: *“Use OpenEvidence to answer …”*. Re-run `make all` anytime to rebuild + re-register; `make help` lists every target; `make kill-all` stops all servers + the relay daemon.

**Already installed? Update in one line:**

make update    # git pull latest release · rebuild server + extension · re-register

Then **reload the browser extension** (`chrome://extensions` → Reload) and reconnect `/mcp`. `make status` shows versions + live health; `make uninstall` removes it. (Inside an AI session you can also just say *“update openevidence-mcp”* — the bundled **install skill** runs the right step and reminds you to reload the extension.)

> Clicking the extension's toolbar icon opens a built-in **how-it-works page** with a live connection check.

> `cookies.json` and a HAR are **optional** — needed only for the legacy `OE_MCP_RELAY_TRANSPORT=off` cookie read path, the Python collections tooling, and `npm run doctor` / `login` / `smoke`. See [Optional cookie path](#optional-cookie-path).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 406 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">OpenEvidence MCP</h1>
  2. <p align="center">
  3. Query OpenEvidence from Claude Code, Codex CLI, Antigravity CLI, Claude Desktop, Cursor, Cline, Continue, and any MCP client —
  4. authenticated through your own logged-in browser tab. No API key.
  5. </p>
  6. <p align="center">
  7. <a href="https://www.apache.org/licenses/LICENSE-2.0"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-2d72d9"></a>
  8. <a href="https://github.com/bakhtiersizhaev/openevidence-mcp"><img alt="Based on upstream" src="https://img.shields.io/badge/upstream-bakhtiersizhaev%2Fopenevidence--mcp-181717?logo=github"></a>
  9. <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-stdio-1d9a5a"></a>
  10. <a href="https://www.typescriptlang.org"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.9.3-3178c6"></a>
  11. <img alt="Node" src="https://img.shields.io/badge/Node-%3E%3D20-339933?logo=node.js&logoColor=white">
  12. <img alt="Auth" src="https://img.shields.io/badge/auth-your%20browser%20tab-E23C1F">
  13. <img alt="DataDome-free" src="https://img.shields.io/badge/DataDome-bypassed-16a34a">
  14. <img alt="Fire and forget" src="https://img.shields.io/badge/oe__ask-fire--and--forget-0ea5e9">
  15. <img alt="BibTeX" src="https://img.shields.io/badge/citations-BibTeX-0f766e">
  16. <img alt="Crossref" src="https://img.shields.io/badge/validation-Crossref-f97316">
  17. <img alt="Unofficial" src="https://img.shields.io/badge/OpenEvidence-unofficial-yellow">
  18. </p>
  19. ## Architecture
  20. <picture>
  21. <source media="(prefers-color-scheme: dark)" srcset="docs/architecture-dark.svg">
  22. <img alt="openevidence-mcp architecture" src="docs/architecture.svg">
  23. </picture>
  24. ## What it does
  25. OpenEvidence protects its API with bot detection that blocks plain server requests. This project removes that problem: when your AI tool asks OpenEvidence a question, the request is run **inside your own logged-in OpenEvidence browser tab** — so it carries your genuine browser session and is never challenged.
  26. A small **Chromium browser extension** lends its session to a localhost relay; the MCP server speaks to that relay. The extension is a narrowly allowlisted authenticated fetch bridge — all the OpenEvidence logic stays in the local server, and **your browser login is the only OpenEvidence credential**. No API key, no cookie file, no Playwright, no headless browser.
  27. 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 any OpenEvidence data in this repository.
  28. ## How it works
  29. Nothing navigates or pops up — the tab stays where it is. The extension only ever talks to `openevidence.com` and your local relay (`127.0.0.1`). The relay runs as a **shared daemon** that owns port 8787 and outlives every session, so any number of Claude/Codex sessions funnel through the **one** logged-in tab.
  30. ## Quick start
  31. ```bash
  32. git clone https://github.com/htlin222/openevidence-mcp.git
  33. cd openevidence-mcp
  34. make all # installs deps · builds the MCP server + relay extension ·
  35. # registers the server into Claude and Codex (whichever CLI you have)
  36. ```
  37. Then the one manual step `make all` prints (a browser action that can't be scripted):
  38. 1. **Load the extension** — open `chrome://extensions` (Chrome / Edge / Brave / Arc / Vivaldi / Opera) → turn on **Developer mode** → **Load unpacked** → select `extension/dist`.
  39. 2. **Stay logged in to [openevidence.com](https://www.openevidence.com)** in that browser, and keep a tab open. That login _is_ your authentication.
  40. 3. **Run your AI tool.** The server auto-starts the relay and connects to the extension.
  41. Verify and go:
  42. ```bash
  43. curl -s http://127.0.0.1:8787/health # expect {"ok":true,"connected":true,"version":1,...}
  44. ```
  45. Then just ask, in any MCP client: _“Use OpenEvidence to answer …”_. Re-run `make all` anytime to rebuild + re-register; `make help` lists every target; `make kill-all` stops all servers + the relay daemon.
  46. **Already installed? Update in one line:**
  47. ```bash
  48. make update # git pull latest release · rebuild server + extension · re-register
  49. ```
  50. Then **reload the browser extension** (`chrome://extensions` → Reload) and reconnect `/mcp`. `make status` shows versions + live health; `make uninstall` removes it. (Inside an AI session you can also just say _“update openevidence-mcp”_ — the bundled **install skill** runs the right step and reminds you to reload the extension.)
  51. > Clicking the extension's toolbar icon opens a built-in **how-it-works page** with a live connection check.
  52. > `cookies.json` and a HAR are **optional** — needed only for the legacy `OE_MCP_RELAY_TRANSPORT=off` cookie read path, the Python collections tooling, and `npm run doctor` / `login` / `smoke`. See [Optional cookie path](#optional-cookie-path).
  53. ## One tab, many sessions
  54. The relay is a standalone daemon (auto-spawned; run/inspect with `npm run relay`) that owns port 8787 and is shared by every MCP server. You can run OpenEvidence from **any number of Claude/Codex sessions at once** — they all flow through the single logged-in tab. The daemon:
  55. - **outlives session restarts** and is respawned automatically if it dies (a crashed daemon is replaced and the in-flight request retried);
  56. - is **idempotent** — a second daemon that loses the port race exits cleanly;
  57. - reports `version` + `pid` on `/health`, so an upgrade replaces a stale daemon from an older build.
  58. ## Asking questions
  59. After registration, ask your MCP client in plain English and mention OpenEvidence — the agent calls `oe_ask` automatically.
  60. ```text
  61. Use OpenEvidence to answer: DLBCL frontline treatment landscape NCCN v3.2026. Include citations and BibTeX.
  62. Use OpenEvidence to compare Pola-R-CHP vs R-CHOP in untreated DLBCL. Include trial citations and BibTeX.
  63. Use OpenEvidence to review current evidence for SGLT2 inhibitors in HFpEF. Include citations and BibTeX.
  64. Use OpenEvidence to find guideline-supported anticoagulation options for cancer-associated thrombosis.
  65. ```
  66. ### Fire-and-forget by default
  67. `oe_ask` returns `{article_id, status:"pending"}` **the moment the question is submitted**, freeing the tab for other sessions instead of holding the call for the whole generation:
  68. ```jsonc
  69. // oe_ask → returns instantly
  70. { "article_id": "…", "status": "pending" }
  71. // oe_article_get(article_id) → the finished answer, when ready
  72. { "article_id": "…", "status": "success", "extracted_answer_raw": "…", "figures": […], "artifacts": { … } }
  73. ```
  74. - Fetch the answer later with **`oe_article_get(article_id)`** — pass `wait_for_completion: true` there to block until it's ready.
  75. - For one-shot blocking (submit and wait in a single call), pass `wait_for_completion: true` to **`oe_ask`** itself.
  76. A completed article returns the OpenEvidence payload and `status`, the `article_id`, the answer markdown as `extracted_answer_raw`, any figures, inline BibTeX as `artifacts.bibtex`, and saved citation files. Pass `include_bibtex: false` to keep the response small while still writing `citations.bib` to disk. Pass `strip_citation_markers: true` to also get `extracted_answer_clean` with the `[1]` / `[1-3]` reference marks removed — handy when quoting the answer into notes.
  77. ### Question pacing — stay under your hourly ask limit
  78. OpenEvidence caps how many **questions** you can ask per account over time. Only
  79. `oe_ask` spends that budget — a new question _and_ every follow-up is one ask.
  80. Everything else (`oe_article_get`, `oe_answers_search`, `oe_history_list`,
  81. `oe_public_get`, `oe_auth_status`, `oe_health`, collections) is free of it.
  82. To avoid bursts that trip the limit, `oe_ask` **paces submissions**: it waits
  83. (never errors) so consecutive asks are at least `OE_MCP_ASK_MIN_INTERVAL_MS`
  84. apart (default 1000 ms ≈ 1 question/second). The wait is coordinated across all
  85. MCP sessions through the shared SQLite `ask_log`, so several Claude/Codex windows
  86. can't collectively exceed the rate. Every `oe_ask` reply carries
  87. `ask_pacing: { waited_ms, asks_last_hour }`, and `oe_health` reports
  88. `asks_last_hour` so you can see how many questions you've spent in the trailing
  89. hour at a glance. Set `OE_MCP_ASK_MIN_INTERVAL_MS=0` to disable pacing.
  90. The biggest saver, though, is **not re-asking**: `oe_answers_search` finds a past
  91. answer and `oe_article_get` serves it from cache — both cost zero questions.
  92. ### Follow-up questions — continue the same conversation
  93. Every completed answer carries **`follow_up_questions`** — the suggestions OpenEvidence renders under the answer (e.g. _"How does adjuvant therapy choice differ in elderly patients?"_). To ask any of them (or your own) **in the same conversation thread**, call `oe_ask` with `original_article_id` set to the answer's `article_id`:
  94. ```jsonc
  95. // first answer → { article_id: "b752a1c1-…", follow_up_questions: ["How does adjuvant therapy choice differ in elderly patients?", …] }
  96. // oe_ask({ question: "How does adjuvant therapy choice differ in elderly patients?",
  97. // original_article_id: "b752a1c1-…" })
  98. // → a new article that threads on the prior turn — the answer opens
  99. // "Elderly patients with stage III colon cancer…", carrying the earlier context.
  100. ```
  101. You only pass `original_article_id` + the new question — OpenEvidence rebuilds the conversation history server-side (the new article's `inputs.history` is populated for you). Each follow-up answer comes with its own fresh `follow_up_questions`, so you can keep drilling down. `original_article_id` accepts a bare UUID or a full `/ask/<id>` URL.
  102. ### Reading conversation pages by link
  103. Someone sends you an OpenEvidence link? **`oe_public_get(url)`** fetches the server-rendered `/ask/<id>` page and parses it into Q&A turns (question, answer as markdown, references). Auth escalates automatically:
  104. 1. **Relay connected** → the fetch runs inside your logged-in tab, so **your own private conversations work too** (and DataDome never sees it).
  105. 2. **No relay, public link** → a plain anonymous fetch; conversations whose author pressed "make public" are fully server-rendered and need zero setup.
  106. 3. **No relay, private link** → falls back to `cookies.json` when present; otherwise reports clearly that the conversation is private.
  107. Page fetches count against the same account budget as API calls, so they run through the same rate limiter (60 clinical queries/min, self-throttled at 80%). `oe_public_get` also accepts a bare article UUID, and `oe_article_get` / `oe_ask.original_article_id` accept full `/ask/` URLs too.
  108. ### Local answer store — search past answers offline, skip re-fetches
  109. Every completed answer from `oe_ask` / `oe_article_get` is upserted into a local SQLite table (`answers`) in the same file the collections tooling already uses (`~/.openevidence-mcp/db/oe.sqlite`). This gives you two things for free:
  110. - **Full-text search over what you've already asked** — **`oe_answers_search("query")`** verifies the active browser account, then runs an account-scoped FTS5 query across locally stored questions, titles, and answer bodies. It returns highlighted `»…«` snippets without spending a question. Great for "did I already look this up?" before asking again.
  111. ```jsonc
  112. // oe_answers_search({ query: "CAPEOX duration neurotoxicity" })
  113. // → { total_stored, match_count, matches: [{ article_id, title, question, snippet, url, … }] }
  114. ```
  115. The query is FTS5 syntax — plain words are ANDed, `"quoted phrases"` match verbatim, and `AND`/`OR`/`NOT` work. Malformed queries fall back to a literal token search instead of erroring.
  116. - **Cache hits on `oe_article_get`** — fetching an article you've already stored returns instantly from disk with `from_cache: true` and **zero network round-trips** (it doesn't even touch the relay). Pass `refresh: true` to force a re-fetch from OpenEvidence and regenerate the on-disk citation artifacts.
  117. This store persists across reboots (unlike the citation artifacts under the OS temp dir), and only ever holds answers _this MCP fetched_. For your complete server-side history, use `oe_history_list` or the collections sync. Point it elsewhere with `OE_MCP_DB_PATH`; it needs Node ≥ 22 for the built-in `node:sqlite` (no extra dependency).
  118. ### Is the pipeline up? `oe_health` vs `oe_auth_status`
  119. Two health checks, two speeds:
  120. - **`oe_health`** — a millisecond-fast, purely local check of the relay pipeline. It reads the daemon's `/health` and reports whether the daemon is up, whether the browser extension is actually polling (`extension_connected`), the version match, uptime, and served/errored counts — **without any OpenEvidence network call**. Use it to confirm the plumbing before an ask, or to diagnose a stuck relay. Each failure state carries a `hint`.
  121. - **`oe_auth_status`** — the full round-trip: hits `/api/auth/me` through the relay to confirm your **login session** is still valid. Slower, but it's the one that answers "am I actually logged in?".
  122. ## Tools
  123. | Tool | Purpose |
  124. | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  125. | `oe_ask` | Ask a question — fire-and-forget by default (returns a pending `article_id`); `wait_for_completion:true` to block; `original_article_id` to follow up in the same thread |
  126. | `oe_article_get` | Fetch an article by id or `/ask/` URL (the fetch-later half of `oe_ask`); returns `follow_up_questions`; saves artifacts; `wait_for_completion` to block until ready |
  127. | `oe_public_get` | Read a conversation page from an `/ask/<id>` link as Q&A markdown turns — public links need zero setup; private ones use the relay tab or `cookies.json` |
  128. | `oe_article_set_access` | Toggle a conversation's share visibility — `public:true` → link-shareable (`ANYONE_WITH_LINK`), `public:false` → private (`CREATOR_ONLY`); returns the `/ask/<id>` URL (you must own it; relay required) |
  129. | `oe_answers_search` | Full-text search (SQLite FTS5) over every answer this MCP has fetched — offline, zero rate-limit cost; returns highlighted snippets |
  130. | `oe_health` | Millisecond-fast local check of the relay pipeline (daemon + extension) — no network call, unlike `oe_auth_status` |
  131. | `oe_auth_status` | Check `/api/auth/me` through the relay (full network round-trip) |
  132. | `oe_history_list` | Read your OpenEvidence question history |
  133. | `oe_collections_list` | List your collections |
  134. | `oe_collections_get` | Get a collection (incl. nested `questions[]` = membership list) |
  135. | `oe_collections_create` | Create a collection (agent-managed names should start with `#`) |
  136. | `oe_collections_add_article` | Add a chat to a collection |
  137. | `oe_collections_db_init` | Create the local SQLite mirror (idempotent) |
  138. | `oe_collections_sync_history` | Pull `/api/article/list` into the local SQLite chats table |
  139. | `oe_collections_sync_db` | Refresh collections + memberships into SQLite |
  140. | `oe_collections_unsorted` | Chats with no `#`-collection membership; structured JSON |
  141. | `oe_collections_summary` | Counts + last sync timestamps |
  142. | `oe_collections_classify` | Auto-classify unsorted chats using log-odds-ratio signatures learned from your memberships + curated keyword rules |
  143. | `oe_collections_bulk_apply` | Mint missing `#`-collections + add memberships per `[{article_id, hashtags}]` plan |
  144. ## Privacy & security
  145. - The relay listens on **localhost only** (`127.0.0.1:8787`) — nothing is exposed to the network.
  146. - The extension and server store **no OpenEvidence credentials**. The extension stores only a random local relay capability; your OpenEvidence session stays in the browser.
  147. - Ordinary web pages cannot use the relay: the extension endpoints (`/poll`, `/result`) require a random per-install capability header (`x-openevidence-relay-client`). Chromium omits `Origin` on host-permitted extension fetches, so a missing `Origin` is accepted, but any `Origin` that is present must be a `chrome-extension://` one — ordinary web pages always send their Origin and are rejected. CORS never uses a wildcard, and the daemon accepts only the exact OpenEvidence routes/methods used by this project.
  148. - The daemon leases itself to one extension installation at a time, so different browser profiles/accounts are never silently pooled. A stopped installation's lease expires automatically once no request is pending.
  149. - Same-user local processes are inside the localhost trust boundary and can call the daemon-facing `/relay` endpoint; do not run untrusted software under your OS account.
  150. - This repository contains **connector code only** — no OpenEvidence content, datasets, cookies, or account material.
  151. ### Keep the relay running across reboots (macOS)
  152. By default the daemon is spawned by the first MCP call and reaps itself after 10 idle minutes, so between sessions the extension's status page shows "Relay not reachable". To make it permanent, hand its lifecycle to launchd:
  153. ```bash
  154. make autostart # start at login, restart on crash, never idle-reap
  155. make status # shows `autostart: installed (… pid N)`
  156. make autostart-remove # back to on-demand
  157. ```
  158. This installs `~/Library/LaunchAgents/com.htlin.openevidence-mcp.relay.plist` (log: `~/.openevidence-mcp/relay-launchd.log`). `make update` / `rebuild` / `reinstall` restart the daemon onto the fresh build, and `make uninstall` removes the agent. The browser still has to be running with the extension loaded and a logged-in openevidence.com tab — add your browser to **System Settings → General → Login Items** for a fully hands-off boot. On other systems run `npm run relay` under your own service manager with `OE_MCP_RELAY_IDLE_TTL_MS=0`.
  159. ## Troubleshooting
  160. - **Status page says “Extension needs a reload”?** The page could not reach the extension's own background worker — the browser still runs the old service worker after a rebuild/update. Click **Reload** on the extension in `chrome://extensions`; the relay itself is fine.
  161. - **Extension badge not green / `connected:false`?** Make sure you're logged in to openevidence.com in that browser with a tab open, then reload the extension (`chrome://extensions` → ↻).
  162. - **Tools fail with “relay not connected”?** Start your AI tool / MCP server so the daemon comes up, then `curl -s http://127.0.0.1:8787/health`. If a previous build is stuck, `make kill-all` and reconnect the MCP server.
  163. - **Extension says “paired channel required”?** Another browser profile currently owns the relay lease. Stop that extension, wait about 35 seconds with no pending request, then retry from the intended profile.
  164. - **DataDome 403 on the legacy cookie path?** See [Doctor](#doctor) below — relevant only when `OE_MCP_RELAY_TRANSPORT=off`.
  165. ## Register with MCP clients
  166. `make all` already registers Claude Code and Codex CLI. To do it à la carte (or for other clients), register the local stdio server `node /ABSOLUTE/PATH/openevidence-mcp/dist/server.js`. **No env is required** — the browser extension is the login.
  167. ```bash
  168. make install-claude-global # claude mcp add-json --scope user openevidence …
  169. make install-codex-global # codex mcp add openevidence -- node dist/server.js
  170. make install-agy-global # Antigravity CLI (agy-cli)
  171. make install-all # all three
  172. ```
  173. For **Claude Desktop, Cursor, Cline, Continue**, use this `mcpServers` shape (see [`examples/`](examples/) for a full-knobs reference):
  174. ```json
  175. {
  176. "mcpServers": {
  177. "openevidence": {
  178. "command": "node",
  179. "args": ["/ABSOLUTE/PATH/openevidence-mcp/dist/server.js"]
  180. }
  181. }
  182. }
  183. ```
  184. ## Collections sync & auto-sort
  185. `scripts/collection_sort.py` mirrors your chat history and collection memberships into a local SQLite (`~/.openevidence-mcp/db/oe.sqlite`; override with `OE_MCP_DB_PATH`). The routine [`routines/collection-sort.md`](routines/collection-sort.md) walks an MCP client through syncing, surfacing unsorted chats, and applying multi-membership hashtag tags. Convention: collections whose name starts with `#` are **agent-managed**; collections without a leading hash are human-curated and never touched.
  186. The same pipeline is exposed as the `oe_collections_*` MCP tools (the TS server shells out to `scripts/collection_sort.py` via `python3`, overridable with `OE_MCP_PYTHON`).
  187. ```bash
  188. python scripts/collection_sort.py init
  189. python scripts/collection_sort.py sync-history --full # first time
  190. python scripts/collection_sort.py sync-collections
  191. python scripts/collection_sort.py list-unsorted --json # routine reads this
  192. python scripts/collection_sort.py summary
  193. ```
  194. **Account-scoped (schema v2).** Chats, collections, and memberships carry an `account` column (composite primary keys), so one DB can mirror multiple OpenEvidence logins without mixing them. The account is resolved from `/api/auth/me`; override with `--account EMAIL`. A v1 DB auto-migrates on first open — pre-v2 rows are tagged `--legacy-account` (default `legacy`; or `OE_MCP_LEGACY_ACCOUNT`).
  195. ### Schedule the sync (macOS)
  196. 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 mirror fresh:
  197. ```bash
  198. bash scripts/install_launchd.sh # daily 02:00 (OE_MCP_SYNC_HOUR / OE_MCP_SYNC_MINUTE)
  199. launchctl start com.htlin.openevidence-mcp.sync # fire once to verify
  200. tail -30 ~/.openevidence-mcp/logs/sync.log
  201. bash scripts/install_launchd.sh --uninstall # remove
  202. ```
  203. The wrapper (`scripts/collection_sync_cron.sh`) appends one block per run to `~/.openevidence-mcp/logs/sync.log`. It takes an optional mode flag:
  204. | Mode | Behavior |
  205. | ----------- | -------------------------------------------------------------------- |
  206. | (default) | sync only — chats accumulate as `unsorted` until you run the routine |
  207. | `--dry-run` | sync + classify; writes `proposed-plan.json` for review, no apply |
  208. | `--auto` | sync + classify + bulk-apply + reconcile; fully autonomous sort |
  209. `scripts/classify.py` runs offline (no API): a per-tag log-odds-ratio signature (Monroe et al. 2008) built from your memberships every run, OR'd with curated keyword rules. Validate with `python scripts/classify.py validate`. Tune headless use via `OE_MCP_AUTO_THRESHOLD` (default 12) and `OE_MCP_AUTO_TOP_K` (default 3); switch the job to autonomous mode with `OE_MCP_SYNC_MODE=--auto bash scripts/install_launchd.sh`.
  210. ## Citation artifacts
  211. Completed `oe_ask` / `oe_article_get` calls save artifacts under `${OE_MCP_ARTIFACT_DIR}/<article_id>/` (default OS temp dir + `openevidence-mcp`; on macOS, `/tmp` may resolve under `/var/folders/.../T/`):
  212. | File | Purpose |
  213. | -------------------------- | ------------------------------------ |
  214. | `answer.md` | Extracted markdown answer |
  215. | `article.json` | Full OpenEvidence article payload |
  216. | `citations.json` | Parsed structured citations |
  217. | `citations.bib` | BibTeX bibliography |
  218. | `crossref-validation.json` | Post-hoc Crossref validation results |
  219. Crossref validation: DOI citations are validated directly; non-DOI citations use a bibliographic query and are marked `candidate` / `not_found` / `error`. Low-similarity matches never overwrite BibTeX metadata, and sources like NCCN guidelines may stay as local OpenEvidence metadata when Crossref has no authoritative match.
  220. These artifact files live under the OS temp dir and can be cleaned up by the system. The **answer body itself is also persisted** to the SQLite `answers` store (see [Local answer store](#local-answer-store--search-past-answers-offline-skip-re-fetches)), which survives reboots and powers `oe_answers_search` and the `oe_article_get` cache.
  221. ## Optional cookie path
  222. The extension relay is the default and recommended path. For headless reads without the extension, set `OE_MCP_RELAY_TRANSPORT=off` to route reads (`oe_history_list`, `oe_article_get`, `oe_collections_*`) over a browser-exported `cookies.json` — asks still need the extension. This path also backs the Python collections tooling and the `npm run doctor` / `login` / `smoke` CLIs.
  223. ```bash
  224. cp /path/to/browser-cookies.json ./cookies.json
  225. make build HAR=/path/to/www.openevidence.com.har # extracts the browser fingerprint, then compiles
  226. npm run login && npm run smoke
  227. ```
  228. `make build` extracts `openevidence-fingerprint.json` from the HAR when present. The fingerprint is **profile-faithful** — the client sends exactly the captured browser's header set, so a HAR from any browser (incl. Safari) stays coherent with the cookie that browser minted.
  229. ### Doctor
  230. `npm run doctor` audits the whole pipeline: relay daemon, extension pairing/version, port sync, and a live read. The live probe goes through **the transport the server actually uses** — the relay when it is connected (`mode: … live probe via relay`), the cookie path only with `OE_MCP_RELAY_TRANSPORT=off` — so stale cookies no longer fail a healthy relay setup. `npm run smoke` follows the same rule and reports its `transport`.
  231. The cookie/fingerprint checks matter when the cookie path fails with a DataDome 403 — most often **after moving to a different computer**:
  232. ```bash
  233. npm run doctor # static checks + a live read probe
  234. npm run doctor -- --offline # static checks only (no network)
  235. npm run doctor -- --json # machine-readable output
  236. ```
  237. It flags `datadome-missing` / `-expired` / `-session` (cookie absent / past expiry / session-scoped), `fingerprint-platform-mismatch` (cookie + fingerprint minted on a different OS — re-mint here), `fingerprint-default` (no fingerprint; built-in signature in use), and `datadome-live` (a live request was actually challenged). Non-zero exit on failure for CI/pre-flight.
  238. ## Make targets
  239. Run `make help` for the grouped, always-current list.
  240. | Target | Purpose |
  241. | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
  242. | `make all` (or bare `make`) | **One-shot setup:** deps + build server + build extension + register into Claude & Codex (skips a CLI that isn't installed) |
  243. | `make update` | **Update to the latest release:** `git pull` + rebuild + re-register (then reload the extension) |
  244. | `make status` | Versions, live relay `/health`, and CLI registration at a glance |
  245. | `make cleanup` | Reap orphan relay daemons + prune stale logs/temp — non-destructive (relay respawns on next use) |
  246. | `make uninstall` | Unregister from the CLIs, stop daemons, remove `dist/` (keeps `~/.openevidence-mcp` + the browser extension) |
  247. | `make autostart` / `autostart-remove` | macOS: keep the relay daemon running across logins/reboots/crashes via launchd · undo it |
  248. | `make help` | Grouped reference of every target |
  249. | `make kill-all` | Stop all MCP servers + the relay daemon and free port 8787 |
  250. | `make relay` | Run the standalone relay daemon in the foreground (debug) |
  251. | `make deps` / `check` / `test` / `smoke` | Force install · type-check · unit tests · auth+history smoke (relay if connected, else cookies) |
  252. | `make build [HAR=…]` | Extract the fingerprint if a HAR is given, then compile TypeScript |
  253. | `make fingerprint HAR=…` | Extract the working browser fingerprint from a HAR |
  254. | `make import-cookies COOKIES=…` | Import and verify cookies |
  255. | `make install-claude-global` / `-codex-global` / `-agy-global` / `install-all` | Register the server with the respective CLI(s) |
  256. ## Environment variables
  257. | Variable | Default | Purpose |
  258. | ---------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  259. | `OE_MCP_RELAY` | `1` | Set `0` to disable the relay entirely |
  260. | `OE_MCP_RELAY_TRANSPORT` | `all` | `all` = every request via the extension; `off` = reads over `cookies.json` |
  261. | `OE_MCP_RELAY_PORT` | `8787` | Relay port (must match the extension) |
  262. | `OE_MCP_RELAY_PID_PATH` | `~/.openevidence-mcp/relay.pid` | Relay daemon pidfile |
  263. | `OE_MCP_RELAY_LOG_PATH` | `~/.openevidence-mcp/relay.log` | Relay daemon log file |
  264. | `OE_MCP_RELAY_MIN_GAP_MS` | `250` | Minimum gap between any two requests the daemon hands to the browser tab, across all sessions |
  265. | `OE_MCP_BASE_URL` | `https://www.openevidence.com` | OpenEvidence base URL |
  266. | `OE_MCP_ARTIFACT_DIR` | OS temp dir + `openevidence-mcp` | Artifact output directory |
  267. | `OE_MCP_CROSSREF_MAILTO` | unset | Optional Crossref polite-pool email |
  268. | `OE_MCP_CROSSREF_VALIDATE` | `1` | Set `0` to skip Crossref validation |
  269. | `OE_MCP_ASK_MIN_INTERVAL_MS` | `1000` | Minimum spacing between questions (`oe_ask`); waits, never errors; `0` disables. Also sets the daemon's ask-lane spacing: one ask in flight, the next dispatched this long after the previous completes |
  270. | `OE_MCP_POLL_INTERVAL_MS` | `1200` | Poll interval when waiting for an answer |
  271. | `OE_MCP_POLL_TIMEOUT_MS` | `180000` | Default poll timeout |
  272. | `OE_MCP_COOKIES_PATH` | `./cookies.json` if present, else `~/.openevidence-mcp/auth/cookies.json` | Cookie file (legacy/optional path) |
  273. | `OE_MCP_FINGERPRINT_PATH` | `./openevidence-fingerprint.json` if present | Browser signature fingerprint (legacy path) |
  274. | `OE_MCP_DB_PATH` | `~/.openevidence-mcp/db/oe.sqlite` | Local SQLite file: collections mirror + the `answers` store (`oe_answers_search`, `oe_article_get` cache) |
  275. | `OE_MCP_PYTHON` | `python3` | Python interpreter the bridge tools spawn |
  276. | `OE_MCP_LEGACY_ACCOUNT` | `legacy` | Label for pre-v2 rows on DB account migration |
  277. ## Project files
  278. - [extension/README.md](extension/README.md) — the browser-extension relay (and its built-in [README.html](extension/README.html) how-it-works page)
  279. - [README.AI.md](README.AI.md) — agent install playbook
  280. - [src/server.ts](src/server.ts) — MCP tools
  281. - [src/relay-server.ts](src/relay-server.ts) — the localhost relay (extension-facing + `/relay` bridge)
  282. - [src/relay-client.ts](src/relay-client.ts) / [src/relay-daemon.ts](src/relay-daemon.ts) — shared-daemon client + standalone daemon
  283. - [src/citations.ts](src/citations.ts) — citation extraction, BibTeX, Crossref validation
  284. - [src/doctor.ts](src/doctor.ts) — stale DataDome cookie diagnostics (legacy path)
  285. - [docs/plans/2026-06-04-shared-relay-daemon-design.md](docs/plans/2026-06-04-shared-relay-daemon-design.md) — relay daemon design doc
  286. - [examples/](examples/) — MCP client config samples
  287. ## Copyright, trademark, and medical disclaimer
  288. 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.
  289. 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.
  290. 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.
  291. 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.
  292. ## License and attribution
  293. Apache-2.0. Keep [LICENSE](LICENSE) and [NOTICE](NOTICE) when redistributing.
  294. Based on OpenEvidence MCP by Bakhtier Sizhaev: `https://github.com/bakhtiersizhaev/openevidence-mcp`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.