{
  "markdown": "# OpenEvidence MCP (Unofficial)\n\nOpenEvidence MCP is an unofficial Model Context Protocol server that connects OpenEvidence to Codex, Claude Code, Claude Desktop, Cursor, Cline, Continue, and other MCP-compatible clients through your own authenticated browser session.\n\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-2d72d9)](https://www.apache.org/licenses/LICENSE-2.0)\n[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-339933)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178c6)](https://www.typescriptlang.org/)\n[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.26.0-1d9a5a)](https://www.npmjs.com/package/@modelcontextprotocol/sdk)\n[![Playwright](https://img.shields.io/badge/Playwright-1.58.2-4f46e5)](https://playwright.dev/)\n\n> [!IMPORTANT]\n> This project is unofficial and is not affiliated with OpenEvidence. It does not provide medical advice, does not bypass access controls, and should only be used with your own OpenEvidence account in compliance with applicable terms, privacy rules, and clinical governance requirements.\n\nTranslations: [Русский](README.ru.md) | [Español](README.es.md) | [简体中文](README.zh-Hans.md) | [繁體中文（台灣）](README.zh-Hant-TW.md) | [한국어](README.ko.md) | [हिन्दी](README.hi.md)\n\n## Agent Onboarding & Installation\n\nUsing Codex, Claude Code, Cursor, or another local AI coding agent? You can let the agent handle the entire setup, compilation, and local MCP configuration for you!\n\nCopy and paste this short bootstrap prompt directly into your local AI coding assistant:\n\n```text\nPlease install OpenEvidence MCP for me: clone https://github.com/bakhtiersizhaev/openevidence-mcp, install dependencies, run build, auto-configure this MCP server in my local client (Claude Desktop/Codex/Cursor), guide me through the one-time Edge/Chrome login using `npm run login:session`, and run `npm run smoke` to verify. Keep everything strictly local and secure.\n```\n\nFor the comprehensive, step-by-step setup playbook and rules, see **[docs/AGENT_INSTALL_PROMPT.md](docs/AGENT_INSTALL_PROMPT.md)**.\n\n## What it does\n\nOpenEvidence MCP runs a local stdio MCP server that lets MCP clients use your existing OpenEvidence browser session for:\n\n- checking whether the saved session is authenticated;\n- listing your OpenEvidence question/article history;\n- fetching a full article payload by ID;\n- asking an OpenEvidence research question and optionally waiting for completion;\n- polling an existing OpenEvidence article until it completes.\n\nNo official OpenEvidence API token is required.\n\n## What it does NOT do\n\n- It is not affiliated with, endorsed by, or approved by OpenEvidence.\n- It does not provide medical advice or replace clinical judgment.\n- It does not bypass authentication, paywalls, or access controls.\n- It does not collect credentials.\n- It does not send your browser session state anywhere except to OpenEvidence through local requests from your machine.\n- It should not be used for patient-specific diagnosis or treatment decisions without appropriate human review.\n\n## Who it is for\n\n- clinicians using their own OpenEvidence account;\n- medical researchers;\n- AI operators building evidence-research workflows;\n- MCP developers integrating local tools with Codex, Claude, Cursor, Cline, Continue, or similar clients.\n\n## Tested / Target Clients\n\nThis project is designed for MCP-compatible clients and local agent workflows. Only Codex and Claude-style local configuration examples are maintained in this repository unless otherwise noted.\n\n| Client | Status | Notes |\n| --- | --- | --- |\n| OpenAI Codex / Codex CLI / Codex app | Target | Recommended local MCP workflow. |\n| Claude Code | Target | Recommended agent workflow. |\n| Claude Desktop / Claude app with MCP support | Target | Local MCP server configuration. |\n| Cursor | Compatible | MCP-compatible IDE workflow. |\n| Cline | Compatible | VS Code agent workflow. |\n| Continue | Compatible | Open-source IDE assistant workflow. |\n| VS Code / GitHub Copilot environments with MCP support | Experimental | Depends on local MCP support and client configuration. |\n| Windsurf / Zed / Replit / Sourcegraph-style MCP hosts | Experimental | Not guaranteed unless tested. |\n| Gemini CLI / Google Antigravity-style agent environments | Experimental | Watchlist/ecosystem target, not a maintained example. |\n\nOther MCP-compatible hosts may work as well, but the examples in this repository focus on Codex and Claude-style local MCP configuration.\n\n## Features\n\n| Tool | Purpose | Auth required | Side effects |\n| --- | --- | --- | --- |\n| `oe_auth_status` | Checks whether the saved OpenEvidence browser session is authenticated. | Yes, local browser profile must be logged in. | None. |\n| `oe_history_list` | Lists prior OpenEvidence articles with optional pagination and search. Returns a privacy-reduced list unless `include_raw=true` is explicitly requested. | Yes. | None. |\n| `oe_article_get` | Fetches an article by ID and returns normalized fields (`status`, `is_complete`, `question`, `answer_text`). Raw payload is opt-in with `include_raw=true`. | Yes. | None. |\n| `oe_article_wait` | Waits for an existing article ID to complete; useful after non-blocking `oe_ask`. | Yes. | None. |\n| `oe_ask` | Creates an OpenEvidence research question and optionally waits for the article to complete. | Yes. | Creates a question/article in your OpenEvidence account. |\n\n## Agent Tool-Calling Notes\n\nThe MCP server includes built-in instructions and a prompt named `openevidence_research_workflow` for clients that expose MCP prompts.\n\nRecommended agent workflow:\n\n1. Call `oe_auth_status` when auth state is unknown.\n2. Use `oe_history_list` only when the user wants prior OpenEvidence work or an article ID.\n3. Use `oe_article_get` when you already have an article ID.\n4. For long research questions, call `oe_ask` with `wait_for_completion=false`, then call `oe_article_wait` with the returned `article_id`.\n5. Use `original_article_id` only for true follow-up continuity. Omit it for fresh questions to avoid stale thread context.\n6. Treat outputs as evidence-research context, not medical advice, diagnosis, or clinical orders.\n\nRelated commands:\n\n| Command | Purpose |\n| --- | --- |\n| `npm run login:session` | Recommended one-time login. Opens Chrome/Edge with the local OpenEvidence MCP profile. |\n| `npm run login` | Legacy/development Playwright login flow that also uses the local profile. |\n| `npm run login:browser` | Legacy system-browser login/export flow for debugging Google SSO issues. |\n| `npm run smoke` | Verifies auth and basic OpenEvidence connectivity. |\n\n## Requirements\n\n- Node.js 20+\n- npm 10+\n- OpenEvidence account\n- macOS, Windows, or Linux\n- Chromium installed by Playwright (`npx playwright install chromium`)\n\n## Availability Note\n\nOpenEvidence availability may depend on region, account eligibility, and OpenEvidence policy. Public materials in May 2026 indicate verified U.S. HCP/NPI-centered access and EU/U.K. unavailability; this project does not bypass those restrictions.\n\nUseful references:\n\n- [OpenEvidence homepage](https://www.openevidence.com/)\n- [OpenEvidence API/product page](https://www.openevidence.com/product/api)\n- [OpenEvidence Privacy Policy](https://www.openevidence.com/policies/privacy)\n\n## Quick Start\n\n### macOS\n\n```bash\ngit clone https://github.com/bakhtiersizhaev/openevidence-mcp.git\ncd openevidence-mcp\n./scripts/setup-macos.sh\nnpm run login:session\nnpm run smoke\n```\n\n### Ubuntu/Linux\n\n```bash\ngit clone https://github.com/bakhtiersizhaev/openevidence-mcp.git\ncd openevidence-mcp\n./scripts/setup-ubuntu.sh\nnpm run login:session\nnpm run smoke\n```\n\n### Windows PowerShell\n\n```powershell\ngit clone https://github.com/bakhtiersizhaev/openevidence-mcp.git\ncd openevidence-mcp\n.\\scripts\\setup-windows.ps1\nnpm run login:session\nnpm run smoke\n```\n\n## Login Flow\n\nRecommended one-time login:\n\n```bash\nnpm run login:session\n```\n\nThe command opens Chrome or Edge with a local OpenEvidence MCP browser profile. Sign in to OpenEvidence with your own account, confirm the normal OpenEvidence page loads, close that browser window, return to the terminal, and press Enter.\n\nDefault local profile path:\n\n- macOS/Linux: `~/.openevidence-mcp/browser-profile`\n- Windows: `%USERPROFILE%\\.openevidence-mcp\\browser-profile`\n\nThe MCP server reuses this same local profile during its process lifetime. It may start a minimized local browser process for OpenEvidence calls, but it does not install an extension, expose a public network service, export cookies, or ask for your password.\n\nLegacy/development flow:\n\n```bash\nnpm run login\n```\n\nIf Google sign-in says the browser or app may not be secure during the legacy flow, use the session login instead:\n\n```bash\nnpm run login:session\n```\n\nDo not share browser profile files, storage-state files, cookies, screenshots with private account data, or patient-identifiable information.\n\n## MCP Client Setup\n\nBuild before registering the server:\n\n```bash\nnpm run build\n```\n\n### Automatic Setup (Recommended)\n\nYou can automatically register the OpenEvidence MCP server with your favorite client using the built-in installer:\n\n* **Claude Desktop** (`claude-app`):\n  ```bash\n  npx openevidence-mcp install --client claude-app\n  # or via npm shortcut:\n  npm run install:claude-app\n  ```\n* **Codex Desktop** (`codex-app`):\n  ```bash\n  npx openevidence-mcp install --client codex-app\n  # or via npm shortcut:\n  npm run install:codex-app\n  ```\n* **Claude Code** (`claude-code`):\n  ```bash\n  npx openevidence-mcp install --client claude-code\n  # or via npm shortcut:\n  npm run install:claude-code\n  ```\n* **Codex CLI** (`codex-cli`):\n  ```bash\n  npx openevidence-mcp install --client codex-cli\n  # or via npm shortcut:\n  npm run install:codex-cli\n  ```\n* **Google Antigravity** (`antigravity`):\n  ```bash\n  npx openevidence-mcp install --client antigravity\n  # or via npm shortcut:\n  npm run install:antigravity\n  ```\n* **Cursor** (`cursor`):\n  ```bash\n  npx openevidence-mcp install --client cursor\n  # or via npm shortcut:\n  npm run install:cursor\n  ```\n* **Windsurf** (`windsurf`):\n  ```bash\n  npx openevidence-mcp install --client windsurf\n  # or via npm shortcut:\n  npm run install:windsurf\n  ```\n\nTo uninstall, you can run:\n```bash\nnpx openevidence-mcp uninstall --client <client-id>\n```\n\n---\n\n### Manual Setup\n\n### Codex\n\nAdd this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.openevidence]\ncommand = \"node\"\nargs = [\"/ABSOLUTE/PATH/openevidence-mcp/dist/server.js\"]\nstartup_timeout_sec = 60\n```\n\nWindows example:\n\n```toml\n[mcp_servers.openevidence]\ncommand = \"node\"\nargs = [\"C:\\\\Users\\\\<user>\\\\openevidence-mcp\\\\dist\\\\server.js\"]\nstartup_timeout_sec = 60\n```\n\n### Claude Desktop\n\nAdd this to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"openevidence\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABSOLUTE/PATH/openevidence-mcp/dist/server.js\"]\n    }\n  }\n}\n```\n\n### Cursor, Cline, Continue\n\nUse the same stdio server shape if your client supports MCP server command/args configuration:\n\n```json\n{\n  \"command\": \"node\",\n  \"args\": [\"/ABSOLUTE/PATH/openevidence-mcp/dist/server.js\"]\n}\n```\n\nExample configs are in `examples/`.\n\n## Verify\n\n```bash\nnpm run smoke\n```\n\nExpected result with a valid session:\n\n- `ok: true`\n- `authenticated: true`\n- a redacted history preview\n\nIf smoke fails with an auth error, run `npm run login:session` again. Smoke requires a real OpenEvidence account session and will not pass in a clean CI environment unless a local session profile is available.\n\nBy default, smoke output redacts account and history content. Use `npm run smoke -- --verbose` only in a private terminal if raw account/history payloads are needed for debugging.\n\nDeveloper checks:\n\n```bash\nnpm test\nnpm run build\nnpm run check\n```\n\n## Security Notes\n\n- Treat browser profiles, `storage-state.json`, and cookies as secrets.\n- Do not commit `.env`, session state, screenshots with account data, or patient-identifiable information.\n- Use only your own OpenEvidence account.\n- Keep MCP client configs pointed at the built local server path you control.\n- Review tool calls from autonomous agents before using outputs in clinical or operational workflows.\n- See `SECURITY.md` for vulnerability reporting and supported scope.\n\n## Troubleshooting\n\nSee `docs/TROUBLESHOOTING.md` for detailed recovery steps.\n\nCommon fixes:\n\n- `authenticated: false`: rerun `npm run login:session`.\n- Google says browser is not secure in the legacy login flow: run `npm run login:session`.\n- Browser install errors: run `npx playwright install chromium`.\n- MCP client cannot start server: confirm `npm run build` succeeded and use an absolute path to `dist/server.js`.\n- Windows path issues: escape backslashes in JSON/TOML or use full absolute paths.\n- Node errors: confirm `node --version` is 20 or newer.\n- OpenEvidence UI/API changed: open an issue with sanitized logs and no private account or patient data.\n- `oe_ask` cannot find the question input or submit button: OpenEvidence UI may have changed; open an issue with sanitized logs and no private account or patient data.\n\n## Roadmap\n\n- Keep tool descriptions compact and agent-friendly.\n- Add focused tests around config and response parsing.\n- Improve smoke diagnostics without exposing session details.\n- Track MCP client setup examples as client configuration formats evolve.\n\n## License & Attribution\n\nApache-2.0 (`LICENSE`) + `NOTICE`.\n\nIf you redistribute, fork, or build derivative versions, keep attribution to:\n\n- Original author: Bakhtier Sizhaev\n- Original repository: `https://github.com/bakhtiersizhaev/openevidence-mcp`\n\nSuggested attribution line:\n\n```text\nBased on OpenEvidence MCP by Bakhtier Sizhaev - https://github.com/bakhtiersizhaev/openevidence-mcp\n```\n\n## Star History\n\n<a href=\"https://star-history.com/#bakhtiersizhaev/openevidence-mcp&Date\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=bakhtiersizhaev/openevidence-mcp&type=Date&theme=dark\" />\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=bakhtiersizhaev/openevidence-mcp&type=Date\" />\n    <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=bakhtiersizhaev/openevidence-mcp&type=Date\" />\n  </picture>\n</a>\n\n",
  "bytes": 14325,
  "sha": "ed4bcdae149f871c2fe50b040e91d676601b8fe5b23e59819f45d193fe7136c1",
  "repo_slug": "bakhtiersizhaev/openevidence-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bakhtiersizhaev_openevidence_m_7643d593/readme"
}