annota
paper note tool for zotero+claude code
Ask AI about annota
Powered by Claude ยท Grounded in docs
I know everything about annota. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Annota โ AI-Powered Paper Annotation Assistant
Turn your PDF library into an intelligent research assistant.
AI reads your papers, highlights key findings, explains formulas, and writes structured notes โ all saved back to your reference manager.
Features ยท Quick Start ยท Usage Examples ยท Screenshots ยท Roadmap
What Can It Do?
| You say... | AI does... |
|---|---|
| "้ซไบฎๆ่ฆไธญ็ๅ็ฐ็ปๆ" (Highlight findings in the abstract) | Reads the abstract, identifies findings, highlights them in green |
| "่งฃ้็ฌฌ3้กต็ๅ ฌๅผ" (Explain the formulas on page 3) | Extracts the formula, adds an explanation as a note annotation |
| "ๅไธไปฝ็ปๆๅ้ ่ฏป็ฌ่ฎฐ" (Write a structured reading note) | Generates a note with contributions, methods, results, limitations โ saved to your library |
| "ไปฅ MICRO ๅฎก็จฟไบบ่ง่งๅฎก้ " (Review as a MICRO reviewer) | Produces a structured review with scores and actionable feedback |
AI reads the paper โ understands content โ creates precise annotations
AI generates a structured reading summary with key findings, methods, and conclusions
โจ Features
9 MCP Tools
| Tool | What it does |
|---|---|
search_zotero_items | Search by title / author / key |
list_zotero_items | Browse recent items |
get_item_metadata | Get authors, year, venue, DOI |
get_pdf_text_bulk | Extract full text (no coords, fast) |
get_pdf_layout_text | Extract text + precise coordinates |
list_annotations | View existing annotations |
create_pdf_annotation | Create highlight / underline |
batch_annotate | Create multiple annotations at once |
add_child_note | Add a note to any item |
3 Claude Code Skills (Slash Commands)
| Command | Function |
|---|---|
/annota-annotate | Smart annotation with semantic color coding |
/annota-summarize | Structured reading notes saved to your library |
/annota-review | Simulated peer review with scoring rubric |
Smart Design
- Two-phase workflow โ Reads full text first (cheap), then only gets coordinates for target sentences (precise). Reduces context usage by 63โ80%.
- Auto-skip references โ Detects "References" section and skips it. A 21-page paper extracts only 13 pages.
- Batch annotations โ Creates 10 highlights in 1 API call instead of 10.
- Friendly errors โ Write failures return helpful messages instead of crashing.
๐ Quick Start (3 Minutes)
Step 1: Clone & Install
git clone https://github.com/dengls24/annota.git
cd annota
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
# source .venv/bin/activate
pip install pymupdf mcp
Step 2: Configure Claude Code
Add to ~/.claude.json (or via Claude Code Settings > MCP Servers):
Windows:
{
"mcpServers": {
"annota": {
"command": "C:/path/to/annota/.venv/Scripts/python.exe",
"args": ["C:/path/to/annota/annota/server.py"],
"env": {
"ZOTERO_DATA_DIR": "C:/Users/YourName/Zotero"
}
}
}
}
macOS / Linux:
{
"mcpServers": {
"annota": {
"command": "/path/to/annota/.venv/bin/python",
"args": ["/path/to/annota/annota/server.py"],
"env": {
"ZOTERO_DATA_DIR": "/Users/YourName/Zotero"
}
}
}
}
Finding your Zotero data directory:
- Windows: Zotero โ Edit โ Settings โ Advanced โ Data Directory Location (default:
C:\Users\YourName\Zotero)- macOS: Zotero โ Settings โ Advanced โ Data Directory Location (default:
~/Zotero)- Linux: default
~/Zotero
Step 3: Use It
Just talk to Claude naturally:
# One command to read a full paper:
/annota-read "path/to/paper.pdf"
# Or natural language:
# Highlight the findings in this paper's abstract in green
"/Users/yourname/Zotero/storage/ABCD1234/paper.pdf"
Or use slash commands:
/annota-read "path/to/paper.pdf"
/annota-annotate "path/to/paper.pdf"
/annota-summarize "path/to/paper.pdf"
/annota-review "path/to/paper.pdf" ISCA
macOS path tip: Drag a file from Finder into the terminal to get its full path, or right-click โ "Copy as Pathname".
(Optional) Install Skills Globally
# Make skills available in all projects
cp -r .claude/skills/ ~/.claude/skills/
๐ Usage Examples
Example 1: Highlight Key Findings
Input:
ๆ่ฟ็ฏ่ฎบๆๆ่ฆไธญ็ๅ็ฐ็ปๆ็จ็ปฟ่ฒๆ ๅบๆฅ
(Highlight the findings in this paper's abstract in green)
"E:\Zotero\storage\ABCD1234\Song et al. - 2025 - AI washing.pdf"
Result:
AI identifies findings in the abstract and highlights them in green
Example 2: Annotate Hypotheses & Theories
Input:
ๆ ๆณจ่ฎบๆไธญ็ๅ่ฎพ(H1, H2)๏ผๅนถ็จไธญๆ่งฃ้ๆฏไธชๅ่ฎพ็็่ฎบๅบ็ก
(Annotate the hypotheses (H1, H2) and explain the theoretical basis of each in Chinese)
Result:
Hypotheses highlighted in yellow, with Chinese explanation notes for the underlying theory
Example 3: Explain Formulas
Input:
่งฃ้่ฎบๆไธญ็ๆ ธๅฟๅ
ฌๅผ๏ผๆทปๅ ไธญๆๆณจ้
(Explain the key formulas in this paper, add Chinese annotations)
Result:
DID model formula annotated with variable explanations in Chinese
Example 4: Policy Implications & Conclusion Notes
Input:
ๆ ๆณจ็ป่ฎบ้จๅ็ๆฟ็ญๅฏ็คบ๏ผๆทปๅ ไธญๆๆป็ป็ฌ่ฎฐ
(Highlight policy implications in the conclusion, add a Chinese summary note)
Result:
Conclusion highlighted with a structured policy implications note
Example 5: Full Paper Reading Notes
Input:
/annota-summarize "path/to/paper.pdf"
Result:
AI generates a complete reading summary: topic, research question, method, key findings, and implications
Example 6: Detailed Paragraph-by-Paragraph Notes
Input:
้ๆฎต้
่ฏป่ฟ็ฏ่ฎบๆ๏ผไธบๆฏไธช้่ฆๆฎต่ฝๆทปๅ ไธญๆๆนๆณจ
(Read this paper paragraph by paragraph, add Chinese annotations to each important section)
Result:
Each important paragraph gets a Chinese annotation explaining the content
Example 7: The AI Workflow in Action
Here's what Claude Code looks like when processing a paper:
Claude creates a task list, reads the PDF, and calls MCP tools to create annotations step by step
๐จ Color Convention
| Color | Code | Use for |
|---|---|---|
| ๐ก Yellow | #ffd400 | Default / general highlights |
| ๐ข Green | #28CA42 | Results, findings, data |
| ๐ต Blue | #2EA8E5 | Methods, definitions, algorithms |
| ๐ด Red | #ff6666 | Limitations, issues, problems |
| ๐ฃ Purple | #a28ae5 | Contributions, novelty |
โก How It Handles Large PDFs
For papers >10 pages, a two-phase workflow avoids context overflow:
Phase 1 โ Understand (lightweight)
get_pdf_text_bulk(pdf, skip_refs=True)
โ Full text without coordinates
โ AI identifies which sentences to annotate
Phase 2 โ Annotate (precise)
get_pdf_layout_text(pdf, target_page_only)
โ Coordinates for 1โ2 target pages
batch_annotate(pdf, all_annotations)
โ Write everything in one call
Real-world performance:
| Paper | Pages | Old approach | New approach | Savings |
|---|---|---|---|---|
| Conference paper | 2 pages | 41 KB coords | 15 KB text | 63% |
| Journal article | 21 pages | 21 pages extracted | 13 pages (refs skipped at p.13) | 38% |
| Survey paper | 19 pages | 19 pages extracted | 10 pages (refs skipped at p.10) | 47% |
๐ Project Structure
annota/
โโโ annota/ # MCP Server (Python)
โ โโโ server.py # 9 tool registrations
โ โโโ zotero_db.py # SQLite read/write layer
โ โโโ pdf_tools.py # PyMuPDF text extraction
โ โโโ config.py # Constants & configuration
โโโ .claude/skills/ # Claude Code Skills
โ โโโ annota-annotate/SKILL.md # /annota-annotate
โ โโโ annota-summarize/SKILL.md # /annota-summarize
โ โโโ annota-review/SKILL.md # /annota-review
โโโ docs/ # Design documents
โ โโโ annota-guide.md # Usage guide (CN)
โ โโโ large-pdf-design.md # Large PDF handling design
โ โโโ dev-notes.md # Pitfalls & solutions
โ โโโ commercial-plan.md # Commercialization plan
โโโ assets/ # Screenshots
โโโ README.md
โ ๏ธ Known Limitations & Disclaimer
Database Direct Access: Annota writes annotations directly to the Zotero SQLite database, which bypasses Zotero's internal consistency mechanisms. This is a design choice to enable fully offline, local-first annotation workflows without depending on external services. Users are responsible for their own database โ please back up your
zotero.sqlitebefore use. We plan to migrate to the official Zotero Web API / Local API in future versions.
| Limitation | Workaround | Planned Fix |
|---|---|---|
| Direct SQLite write (not officially supported) | Back up your database before use | Migrate to Zotero Local API / Web API |
| Write ops need Zotero closed | Close Zotero before annotating | Local API bridge |
| References detection is heuristic | Pass skip_refs=False if needed | Improve heuristics |
| Tested primarily on Windows | Should work on macOS/Linux โ paths auto-detected | Community testing welcome |
๐บ Roadmap
- Zotero Local API / Web API โ Migrate from direct SQLite to official API for safer writes
- More skills โ
/compare-papers,/extract-tables,/literature-map - Prompt template marketplace โ Share and reuse annotation rules
- Team features โ Shared annotation standards for lab groups
- Multi-backend โ Support Adobe Acrobat, Endnote, and other PDF tools
๐ค Contributing
Issues and PRs are welcome! If you have ideas for new skills or tools, please open an issue.
๐ License
MIT โ Use it freely for research and commercial projects.
Built with MCP + Claude Code
If this project helps your research, consider giving it a โญ
