Skip to main content
Glama
imankgoyal

hypothesis-mcp

by imankgoyal
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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.

Related MCP server: mendeley-mcp

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)).

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers