# principia-mcp
MCP server that gives Claude access to your local Zotero library. Claude discovers papers via metadata search, then reads PDFs directly.
## How It Works
```
You: "What does Mannheim say about conformal gravity?"
│
▼
Claude: search_papers("conformal gravity", collection="mannheim")
│
▼
MCP returns: [{id: 212, title: "Making the Case...", pdf_path: "/home/.../paper.pdf"}]
│
▼
Claude: Read("/home/.../paper.pdf") ← Claude sees equations visually
│
▼
Claude: "Mannheim argues that conformal gravity can explain galaxy rotation curves..."
```
No embeddings, no text extraction. Claude reads PDFs natively.
## Installation
```bash
git clone https://github.com/phelps-matthew/principia-mcp
cd principia-mcp
uv sync
```
## Configure Claude Code
Add the MCP server (user-wide):
```bash
claude mcp add principia -s user -- uv run --directory /path/to/principia-mcp principia-mcp
```
Or for just one project:
```bash
claude mcp add principia -s project -- uv run --directory /path/to/principia-mcp principia-mcp
```
Verify with `claude mcp list` or `/mcp` in a new session.
## MCP Tools
| Tool | Description |
|------|-------------|
| `list_collections()` | List Zotero collections with paper counts |
| `list_papers(collection?, limit?)` | Browse papers in library or collection |
| `search_papers(query, collection?, limit?)` | Keyword search on title/abstract |
| `get_paper(paper_id)` | Get metadata + PDF path for a paper |
## Zotero Integration
Reads directly from `~/Zotero/`:
- `zotero.sqlite` - metadata database
- `storage/[key]/` - PDF files
No export needed. Add a paper to Zotero and it's available immediately.
Set `ZOTERO_DIR` environment variable if your Zotero data is elsewhere.
## Development
```bash
uv sync # Install dependencies
uv run pytest # Run tests
uv run principia-mcp # Run server
uv run mcp dev src/principia_mcp/server.py # Dev/debug mode
```
## Project Structure
```
src/principia_mcp/
├── server.py # FastMCP server, tool definitions
├── models.py # Pydantic models (Paper, Collection)
├── zotero.py # ZoteroReader - reads Zotero SQLite DB
└── search.py # FTS5 index for fast search (optional)
```
