hypothesis-mcp

MCP server for the Hypothesis annotation service. Gives Claude access to your annotations and the ability to read PDFs — including finding which PDF in your library discusses a given topic.

Note: All code written by Claude (Anthropic) under the supervision of Ankit Goyal.

Quick Install (Claude Code)

# 1. Get your API key: https://hypothes.is/account/developer
# 2. Run this in Claude Code:
claude mcp add hypothesis -e HYPOTHESIS_API_KEY=your-key-here -- uvx --from git+https://github.com/imankgoyal/hypothesis-mcp hypothesis-mcp

That's it — no cloning, no venv, no config files. Requires uv.

Tools

Tool	Description
search_annotations	Search annotations by URL, user, group, tag, text
get_annotation	Fetch a single annotation by ID
create_annotation	Create an annotation with optional quote/selectors
update_annotation	Update annotation text or tags
delete_annotation	Delete an annotation
flag_annotation	Flag an annotation for moderation
hide_annotation / unhide_annotation	Hide or unhide an annotation
list_groups / get_group	List or fetch groups
get_user_profile	Fetch the authenticated user's profile
read_pdf	Extract text from a PDF URL (direct or Chrome extension viewer format)
discover_pdfs	Scan all your annotated PDFs and find which ones discuss a topic

Installation

Option A — uvx from GitHub (recommended, no cloning required)

Requires uv to be installed.

claude mcp add hypothesis -e HYPOTHESIS_API_KEY=your-key-here -- uvx --from git+https://github.com/imankgoyal/hypothesis-mcp hypothesis-mcp

Option B — local install

git clone https://github.com/imankgoyal/hypothesis-mcp
cd hypothesis-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
claude mcp add hypothesis \
  -e HYPOTHESIS_API_KEY=your-key-here \
  -- /path/to/hypothesis-mcp/.venv/bin/hypothesis-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hypothesis": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/imankgoyal/hypothesis-mcp", "hypothesis-mcp"],
      "env": {
        "HYPOTHESIS_API_KEY": "your-key-here"
      }
    }
  }
}

Troubleshooting

uvx not found

Claude Code and Claude Desktop launch MCP servers without inheriting your shell PATH, so uvx may not be found even if it works in your terminal.

Fix: Use the full path to uvx. Find it with:

which uvx

Then replace uvx in the install command with the full path, e.g.:

# Claude Code
claude mcp add hypothesis -e HYPOTHESIS_API_KEY=your-key-here -- /Users/yourname/.local/bin/uvx --from git+https://github.com/imankgoyal/hypothesis-mcp hypothesis-mcp

// Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "hypothesis": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/imankgoyal/hypothesis-mcp", "hypothesis-mcp"],
      "env": {
        "HYPOTHESIS_API_KEY": "your-key-here"
      }
    }
  }
}

If uv is not yet installed, follow the uv installation guide — uvx is included.

PDF URL formats

read_pdf accepts both formats:

https://arxiv.org/pdf/2507.05331
chrome-extension://bjfhmglciegochdpefhhlphglcehbmek/pdfjs/web/viewer.html?file=https%3A%2F%2Farxiv.org%2Fpdf%2F2507.05331

Paste either directly — the chrome-extension URL is automatically unwrapped.

Self-hosted Hypothesis

Point the server at your own instance by setting HYPOTHESIS_BASE_URL:

claude mcp add hypothesis \
  -e HYPOTHESIS_API_KEY=your-key-here \
  -e HYPOTHESIS_BASE_URL=https://your-hypothesis-instance.com/api \
  -- uvx hypothesis-mcp

License

Apache 2.0 — see LICENSE. Any modifications must credit Ankit Goyal as the original author and state what was changed (per Apache 2.0 Section 4(b)).