paperqa-mcp-server

What is paperqa-mcp-server?

paperqa-mcp-server gives Claude the ability to read, search, and synthesize across your entire PDF library. It is built on PaperQA2 and points at a Zotero storage folder (or any folder of PDFs), enabling deep reading and question answering across multiple papers.

How to use paperqa-mcp-server?

Install the uv package manager and obtain an OpenAI API key. Run uvx paperqa-mcp-server once to warm the cache, then configure Claude Desktop by adding a paperqa entry in claude_desktop_config.json with the full path to uvx and your API key. Pre‑build a search index with uvx paperqa-mcp-server index (required if you have more than ten unindexed papers). After restarting Claude Desktop, the paper_qa tool appears.

Key features of paperqa-mcp-server

• Deep reading and synthesis across PDFs using PaperQA2
• Indexes and searches an entire Zotero storage folder
• Integrates natively with Claude Desktop via MCP
• Uses OpenAI embeddings and LLMs for internal reasoning
• Pre‑build index avoids runtime latency on large libraries
• Pairs with zotero-mcp for cross‑referencing metadata

Use cases of paperqa-mcp-server

• Ask Claude questions that require evidence from multiple research papers
• Rapidly synthesize findings across hundreds of PDFs in Zotero
• Combine with zotero-mcp to browse library metadata and annotations
• Query personal PDF collections with natural language and get cited answers

FAQ from paperqa-mcp-server

Why does Claude show “Server disconnected”?

Claude Desktop has a short startup timeout. If uv needs to download packages on first launch, it will time out. Fix: run uvx paperqa-mcp-server once from the terminal first.

Why does the server say “Index incomplete” when I query?

The server checks the index before each query. If too many papers are unindexed, it returns a diagnostic message. Fix: run uvx paperqa-mcp-server index to build the full index.

The hammer icon doesn’t appear. What’s wrong?

Make sure you quit Claude Desktop completely (Cmd+Q) and reopened it. Check for JSON syntax errors in claude_desktop_config.json – a missing comma is the most common mistake.

Does paperqa-mcp-server use Claude for its internal reasoning?

No. PaperQA2 uses its own LLM (default gpt-4o-mini) for embeddings and synthesis. You can change the model via environment variables PQA_LLM, PQA_SUMMARY_LLM, and PQA_EMBEDDING.

What are the runtime requirements?

Python managed by uv, an OpenAI API key, and a folder of PDFs (default ~/Zotero/storage). The index is stored locally at ~/.pqa/indexes/. The server uses MCP stdio transport and authenticates via the OPENAI_API_KEY environment variable.