hypothesis-mcp
by imankgoyal
README.md
# hypothesis-mcp
MCP server for the [Hypothesis](https://hypothes.is) 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](https://claude.ai) (Anthropic) under the supervision of [Ankit Goyal](https://github.com/imankgoyal).
## Quick Install (Claude Code)
```bash
# 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](https://docs.astral.sh/uv/getting-started/installation/).
## 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](https://docs.astral.sh/uv/getting-started/installation/) to be installed.
```bash
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
```bash
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`:
```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:
```bash
which uvx
```
Then replace `uvx` in the install command with the full path, e.g.:
```bash
# 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
```
```json
// 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](https://docs.astral.sh/uv/getting-started/installation/) — `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`:
```bash
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](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
Maintenance
ActivityInactive
ResponsivenessNo recent community issues