# covidence-mcp

An MCP connector that lets Claude screen studies in [Covidence](https://app.covidence.org) using its own intelligence — no brittle CSS selectors, no hardcoded click paths.

## How it works

Instead of a static Playwright script, Claude navigates Covidence directly using **Claude in Chrome**. It reads the live page, finds the right buttons by understanding what it sees, and casts votes — the same way a human would. When Covidence updates their UI, nothing breaks.

The MCP server itself is intentionally thin: it stores your inclusion/exclusion criteria per review and keeps a session vote log. All actual browser interaction is handled by Claude.

```
You ──► Claude ──► covidence_screen (MCP)
                        │
                        ▼
              Returns screening prompt
                        │
                        ▼
         Claude navigates Chrome directly
         (read_page → reason → find → click)
                        │
                        ▼
              Votes cast in Covidence
```

---

## Setup

There are two ways to connect, depending on whether you're using Claude Desktop or the claude.ai web app.

---

### Option A — Claude Desktop (local)

**Requirements:** Node.js ≥ 18, Claude Desktop app

```bash
git clone <this repo>
cd covidence-mcp
npm install
npm run build
```

Add to your Claude Desktop config:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "covidence": {
      "command": "node",
      "args": ["/absolute/path/to/covidence-mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop. Done.

---

### Option B — claude.ai web (remote hosting)

Claude.ai supports remote MCP servers over SSE. You deploy this server somewhere public and give Claude the URL — no desktop app required.

**Requirements:** A free account on [Railway](https://railway.app), [Render](https://render.com), or any host that can run Node.js

#### 1. Deploy to Railway (easiest)

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app)

Or manually:

```bash
# Push this folder to a GitHub repo, then:
# 1. Create a new Railway project from that repo
# 2. Railway auto-detects Node.js and runs `npm run build && npm start`
# 3. Set the PORT environment variable (Railway sets this automatically)
```

The server switches to HTTP mode automatically when `PORT` is set. Your public URL will look like:

```
https://covidence-mcp-production.up.railway.app
```

#### 2. Connect to claude.ai

1. Go to **claude.ai → Settings → Integrations**
2. Click **Add custom connector**
3. Enter your server URL: `https://your-deployment.up.railway.app/sse`
4. Save — Claude will confirm the connection

#### Deploy to Render (alternative)

1. Create a new **Web Service** from your GitHub repo
2. Build command: `npm install && npm run build`
3. Start command: `node dist/index.js`
4. Render sets `PORT` automatically

#### Deploy to Fly.io (alternative)

```bash
fly launch
fly deploy
```

Then connect `https://your-app.fly.dev/sse` in Claude's integrations settings.

---

## Usage

Once connected (either way), the workflow is the same.

**First time — tell Claude your login and criteria:**
```
Log in to Covidence with researcher@university.edu, then save these criteria for review 12345:
Include: RCTs and quasi-experimental studies in adults with type 2 diabetes.
Exclude: animal studies, systematic reviews, non-English publications, studies before 2000.
```

**Screen a batch:**
```
Screen the next 20 studies in review 12345.
```

Claude calls `covidence_screen`, opens Covidence in Chrome, reads a batch of abstracts, applies your criteria, and votes on all of them.

**Check progress:**
```
How many studies have we screened today?
```

---

## Tools

| Tool | What it does |
|---|---|
| `covidence_login` | Starts a session and returns Chrome navigation steps for login |
| `covidence_set_criteria` | Saves inclusion/exclusion criteria for a review ID |
| `covidence_screen` | Builds a full screening prompt — Claude uses this to drive Chrome |
| `covidence_log_vote` | Records a vote in the session log |
| `covidence_get_session_log` | Returns all votes cast this session with totals |
| `covidence_nav` | Returns plain-English navigation steps for any specific action |


---

## License

MIT