Which integrations are available for this server?

Provides access to a local Zotero library, allowing for paper discovery via metadata search, collection browsing, and direct reading of PDF files.

How do I use principia-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@principia-mcp find papers about conformal gravity in my Zotero library" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

git clone https://github.com/phelps-matthew/principia-mcp cd principia-mcp uv sync

Configure Claude Code

Add the MCP server (user-wide):

claude mcp add principia -s user -- uv run --directory /path/to/principia-mcp principia-mcp

Or for just one project:

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

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)