# Verbatim MCP Server

An MCP (Model Context Protocol) server for [Verbatim](https://verbatim.krlabs.eu) — a platform of specialized document collections that returns verbatim, cited answers. ACL Anthology is the default collection; pass `collection_ids=[...]` to scope to a different collection or query multiple.

## Features

- **Search papers** by keywords, authors, venues, and years
- **Ask research questions** and get answers with verbatim citations
- **Get paper metadata** and full content
- **Export citations** in BibTeX format
- **Browse** collections, authors, venues, and years
- **Collection-aware** — all tools accept an optional `collection_ids` list (default `["anthology"]`)

---

## Quick Start

### Step 1: Get an API Key

1. Go to [verbatim.krlabs.eu](https://verbatim.krlabs.eu)
2. Sign up / Log in
3. Navigate to **API Keys**
4. Create a new API key and copy it

### Step 2: Set up the MCP server

Choose the setup that matches your environment:

---

## Setup for Claude Code (CLI)

**Option A: Using uvx (no install needed, requires [uv](https://docs.astral.sh/uv/getting-started/installation/))**

```bash
claude mcp add verbatim --transport stdio \
  -e VERBATIM_API_KEY=vb_your_key_here \
  -- uvx verbatim-mcp
```

**Option B: Using pip (works everywhere)**

```bash
pip install verbatim-mcp

claude mcp add verbatim --transport stdio \
  -e VERBATIM_API_KEY=vb_your_key_here \
  -- verbatim-mcp
```

**Option C: Config file**

Add to `~/.claude.json` or your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "verbatim": {
      "type": "stdio",
      "command": "verbatim-mcp",
      "args": [],
      "env": {
        "VERBATIM_API_KEY": "vb_your_key_here"
      }
    }
  }
}
```

Then restart Claude Code or run `/mcp` to verify.

---

## Setup for Claude Desktop App

Edit your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "verbatim": {
      "command": "uvx",
      "args": ["verbatim-mcp"],
      "env": {
        "VERBATIM_API_KEY": "vb_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see "verbatim" in the tools menu (hammer icon).

---

## Setup for OpenAI Codex

**Option A: Via CLI**

```bash
codex mcp add verbatim \
  -e VERBATIM_API_KEY=vb_your_key_here \
  -- uvx verbatim-mcp
```

**Option B: Via config file**

Edit `~/.codex/config.toml`:

```toml
[mcp_servers.verbatim]
command = "uvx"
args = ["verbatim-mcp"]

[mcp_servers.verbatim.env]
VERBATIM_API_KEY = "vb_your_key_here"
```

Then restart Codex or run `/mcp` to verify.

---

## Setup for Cursor / VS Code with Continue

For **Cursor** or **Continue.dev** extension, add to your config:

```json
{
  "mcpServers": {
    "verbatim": {
      "command": "uvx",
      "args": ["verbatim-mcp"],
      "env": {
        "VERBATIM_API_KEY": "vb_your_key_here"
      }
    }
  }
}
```

---

## Verify It's Working

In Claude Code, run:
```
/mcp
```

You should see `verbatim` listed with its tools.

Try asking Claude:
> "Use verbatim to search for papers about attention mechanisms"

---

## Available Tools

Every collection-aware tool accepts an optional `collection_ids: list[str]` parameter (default `["anthology"]`). `verbatim_transform` is collection-agnostic — you supply the context.

| Tool | Description |
|------|-------------|
| `list_collections` | List collections available to your API key |
| `get_collection` | Get metadata for a single collection |
| `query_rag` | Ask a research question, get an answer with citations |
| `verbatim_transform` | Turn any question + context into a verbatim cited answer (no collection) |
| `search_papers` | Search papers by keywords and filters. Pass `include_chunks=true` to also get the matched chunks per paper (no LLM, no quota) |
| `get_paper` | Get metadata for a specific paper |
| `get_paper_content` | Get full text of a paper |
| `get_citation` | Get BibTeX citation |
| `list_authors` | Search authors by name |
| `list_venues` | Browse publication venues |
| `list_booktitles` | Browse proceedings/booktitles |
| `list_years` | List available publication years |

## Example Prompts

Once configured, try these with Claude:

- "Search for papers about transformer efficiency from 2023"
- "What does the research say about attention mechanisms?"
- "Find papers by Ashish Vaswani"
- "Get the BibTeX citation for that paper"
- "List the top venues in the corpus"

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `VERBATIM_API_KEY` | Your API key (required) | - |
| `VERBATIM_API_URL` | API base URL | `https://verbatim.krlabs.eu` |

---

## Troubleshooting

**"Failed to reconnect to verbatim"**
- If using `uvx`, make sure [uv](https://docs.astral.sh/uv/getting-started/installation/) is installed: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Alternatively, use pip instead: `pip install verbatim-mcp` and replace `uvx verbatim-mcp` with just `verbatim-mcp` in your config

**"VERBATIM_API_KEY environment variable is required"**
- Make sure you added the `-e` flag or `env` block with your API key

**Server not showing in `/mcp`**
- Restart Claude Code: `claude` (exit and reopen)
- Check config syntax: `claude mcp list`

**"API error (401): Unauthorized"**
- Your API key is invalid or expired
- Generate a new one at [verbatim.krlabs.eu/api-keys](https://verbatim.krlabs.eu/api-keys)

**"API error (429): Rate limit"**
- You've exceeded your query limit
- Check usage at [verbatim.krlabs.eu/api-keys](https://verbatim.krlabs.eu/api-keys)

---

## Compatibility

MCP (Model Context Protocol) is supported by:
- **Claude Code** (CLI) - `~/.claude.json`
- **Claude Desktop App** - `claude_desktop_config.json`
- **OpenAI Codex** - `~/.codex/config.toml`
- **Cursor** - built-in MCP support
- **Continue.dev** - VS Code/JetBrains extension

---

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Verbatim](https://verbatim.krlabs.eu) - The RAG service
- [MCP Documentation](https://modelcontextprotocol.io) - Learn about MCP
- [Claude Code](https://claude.ai/code) - Claude's coding assistant