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)