Skip to main content
Glama
imankgoyal

hypothesis-mcp

by imankgoyal
OverviewSchemaRelated ServersScoreDiscussions
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 installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/imankgoyal/hypothesis-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server