openevidence
Skill17 starsChanged 3 months agoApache-2.0View on GitHub
Install, manage, troubleshoot, and use the canonical openevidence-mcp server. Use when the user asks to set up or update OpenEvidence MCP, check its relay or login, query OpenEvidence for clinical evidence with citations or BibTeX, retrieve an OE answer or shared conversation, search prior answers, manage collections, or change conversation sharing.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- htlin222/openevidence-mcptheir own version, first seen Nov 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- htlin222/openevidence-mcp★ 83same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 9 are distinctive, and 14 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use the canonical htlin222/openevidence-mcp implementation.
- Distinctive: line 10
Never reimplement the OpenEvidence API, send direct HTTP requests to its private API, or fall back to an exported-cookie Python client.
- Very specific: line 14
If the user wants to install, update, inspect, clean up, or uninstall the MCP, run the matching command from scripts/oe-mcp.sh.
- Very specific: line 15
If the user wants OpenEvidence data and the oe_* MCP tools are available, call those tools directly.
- Very specific: line 17
Read references/tools.md when choosing among the complete tool set.
- Distinctive: line 39
Do not claim setup is complete before the extension is loaded and the client is reconnected.
- Distinctive: line 43
Use the two checks for different questions:
- Very specific: line 45
Call oe_health first to test the local pipeline.
- Very specific: line 46
Call oe_auth_status only after health succeeds to verify that the browser tab is actually logged in.
- Very specific: line 54
Call oe_health when connection state is unknown.
- Very specific: line 55
Call oe_auth_status when login state is unknown or health alone is insufficient.
- Very specific: line 56
Call oe_ask with the user's question.
- Very specific: line 58
Call oe_article_get with that ID.
- Very specific: line 65
Use oe_public_get for an OpenEvidence /ask/<id> link when the user wants readable question-and-answer turns.
- Very specific: line 67
Treat oe_article_set_access as a consequential write:
- Distinctive: line 70
Never make a conversation public if it contains PHI, patient identifiers, medically sensitive details, secrets, or content the user has not …
- Distinctive: line 72
When there is any doubt, keep the conversation private and ask the user to remove sensitive content or confirm the disclosure.
- Very specific: line 74
Use collection create/add/bulk-apply tools only when the user asks to change organization.
- Distinctive: line 84
Do not delete the retained database or remove the browser extension unless the user separately and explicitly requests a full wipe.
- Distinctive: line 88
Keep the MCP server and extension implementation in the upstream repository.
- Distinctive: line 89
Do not copy upstream TypeScript, extension code, protocol code, or API payload logic into this skill.
- Very specific: line 90
Do not use cookies.json as the primary setup.
- Distinctive: line 91
If install/update output asks for an extension reload or MCP reconnect, repeat that requirement clearly to the user.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
OpenEvidence MCP
Use the canonical htlin222/openevidence-mcp implementation. It sends OpenEvidence requests through a localhost relay and a Chromium extension running inside the user's logged-in browser tab.
Never reimplement the OpenEvidence API, send direct HTTP requests to its private API, or fall back to an exported-cookie Python client. Plain server requests are blocked by bot detection. If the MCP tools are unavailable, install or repair the MCP instead.
Route the request
- If the user wants to install, update, inspect, clean up, or uninstall the MCP, run the matching command from
scripts/oe-mcp.sh. - If the user wants OpenEvidence data and the
oe_*MCP tools are available, call those tools directly. - If the user wants OpenEvidence data but the tools are unavailable, do not substitute a direct HTTP client. Install the MCP only when the user asked for setup or authorizes the prerequisite; otherwise explain the missing dependency and ask them to approve installation. Complete the manual browser step and reconnect the MCP client before attempting the query.
- Read
references/tools.mdwhen choosing among the complete tool set.
Resolve the skill directory containing this SKILL.md, then invoke:
bash <skill-directory>/scripts/oe-mcp.sh <install|update|status|cleanup|uninstall>Honor OE_MCP_DIR when the user wants the upstream checkout in a non-default location. The default is ~/openevidence-mcp.
Install and connect
For first-time setup, run scripts/oe-mcp.sh install. The wrapper checks Node.js 22+, clones the canonical repository if necessary, and delegates the build, extension, and MCP-client registration to upstream make all.
Then instruct the user to complete the browser action that cannot be automated:
- Open
chrome://extensionsin Chrome, Edge, Brave, Arc, Vivaldi, or Opera. - Enable Developer mode.
- Choose Load unpacked and select
<openevidence-mcp>/extension/dist. - Stay logged in to
https://www.openevidence.comin that browser. - Reconnect or restart the MCP client so it discovers the newly registered server.
Do not claim setup is complete before the extension is loaded and the client is reconnected.
Verify health and authentication
Use the two checks for different questions:
- Call
oe_healthfirst to test the local pipeline. It checks the relay daemon, extension connection, protocol version, and recent activity without contacting OpenEvidence. - Call
oe_auth_statusonly after health succeeds to verify that the browser tab is actually logged in. This performs a network round trip to/api/auth/methrough the relay.
If oe_health says the daemon is down, trigger an MCP call or run the status command and follow its hint. If the daemon is up but the extension is disconnected, ask the user to load/reload the extension and keep the Chromium browser running. If oe_auth_status fails, ask the user to sign in to OpenEvidence in that same browser.
Ask and retrieve
For a new clinical question:
- Call
oe_healthwhen connection state is unknown. - Call
oe_auth_statuswhen login state is unknown or health alone is insufficient. - Call
oe_askwith the user's question. Keep the default fire-and-forget behavior unless the user explicitly needs a blocking one-shot call. - Capture the returned
article_idand pending status. - Call
oe_article_getwith that ID. Usewait_for_completion: truewhen the current turn should wait for the finished answer; otherwise fetch it later. - Present the OpenEvidence answer as sourced clinical evidence, preserve its citations, and distinguish it from independent medical advice.
To continue a thread, pass the prior article ID or /ask/<id> URL as original_article_id to oe_ask. Prefer oe_answers_search before spending another question when an earlier fetched answer may already cover the topic.
Read links, share, and protect sensitive data
Use oe_public_get for an OpenEvidence /ask/<id> link when the user wants readable question-and-answer turns. Public links can work anonymously; private links require the connected logged-in relay session.
Treat oe_article_set_access as a consequential write:
- Change access only when the user explicitly asks.
- Never make a conversation public if it contains PHI, patient identifiers, medically sensitive details, secrets, or content the user has not reviewed for disclosure.
- State that
public: truemakes the link readable by anyone who has it. - When there is any doubt, keep the conversation private and ask the user to remove sensitive content or confirm the disclosure.
Use collection create/add/bulk-apply tools only when the user asks to change organization. Prefer read-only list, get, summary, search, and unsorted tools for inspection.
Manage the installation
install: clone if needed, build the server and extension, and register supported MCP clients.update: fast-forward the upstream checkout, rebuild, and re-register. Then require the user to reload the extension and reconnect the client.status: show upstream versions, relay health, and client registration.cleanup: reap orphan relay processes and stale temporary state while keeping the installation and user database.uninstall: unregister clients, stop daemons, and remove generated builds. It intentionally keeps~/.openevidence-mcpdata and the browser extension.
Do not delete the retained database or remove the browser extension unless the user separately and explicitly requests a full wipe.
Boundaries
- Keep the MCP server and extension implementation in the upstream repository; this skill is only an orchestration and usage layer.
- Do not copy upstream TypeScript, extension code, protocol code, or API payload logic into this skill.
- Do not use
cookies.jsonas the primary setup. The logged-in browser extension is the default authentication path. - If install/update output asks for an extension reload or MCP reconnect, repeat that requirement clearly to the user.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

