paperqa-mcp-server

Name: paperqa-mcp-server
Author: menyoung

by menyoung

Overview Schema Related Servers Score Discussions

Python

paperqa-mcp-server

Give Claude the ability to read, search, and synthesize across your entire PDF library. Built on PaperQA2.

Point it at your Zotero storage folder (or any folder of PDFs) and ask Claude questions that require deep reading across multiple papers.

Quick start

1. Install uv

uv is a Python package manager. If you don't have it yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installing, restart your terminal so uv is on your PATH.

Verify it works:

uv --version

2. Get an OpenAI API key

PaperQA2 uses OpenAI for embeddings and internal reasoning. Get a key at https://platform.openai.com/api-keys

3. Warm the package cache

The first run downloads ~90 Python packages — this is normal and only happens once. Run this so the packages are cached before Claude Desktop tries to start the server:

uvx paperqa-mcp-server index 2>&1 | head -1

You should see output like Building index: .... Press Ctrl+C to stop (we'll run the real index build in step 6). If you see a Python error instead, something went wrong with the install.

4. Find your full path to uvx

Claude Desktop can't find uvx on its own — you need to give it the full path. Run:

which uvx

This prints something like /Users/yourname/.local/bin/uvx. Copy it — you'll need it in the next step.

5. Add to Claude Desktop

Open Claude Desktop
Go to Settings → Developer → Edit Config
This opens claude_desktop_config.json. Add a paperqa entry inside mcpServers (create mcpServers if it doesn't exist):

{
  "mcpServers": {
    "paperqa": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["paperqa-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Replace the two placeholders:

/Users/yourname/.local/bin/uvx — paste the output of which uvx from step 4
sk-your-key-here — your OpenAI API key from step 2

If your PDFs are somewhere other than ~/Zotero/storage, add a PAPER_DIRECTORY entry to env:

"env": {
  "OPENAI_API_KEY": "sk-your-key-here",
  "PAPER_DIRECTORY": "/full/path/to/your/pdfs"
}

Quit Claude Desktop completely (Cmd+Q, not just close the window) and reopen it
You should see a hammer icon — click it and paper_qa should be listed

6. Pre-build the index

Before Claude can search your papers, the server needs to build a search index. This reads each PDF, splits it into chunks, and sends the chunks to OpenAI's embedding API. With hundreds of papers this takes a while and costs a few dollars in API calls.

If you have more than 10 unindexed papers, the server will refuse to answer queries and tell you to run this step first. A few new papers will be indexed automatically when you query.

export OPENAI_API_KEY=sk-your-key-here
uvx paperqa-mcp-server index

You'll see log lines as each paper is processed. When it finishes, it prints Done.

If this crashes with a rate limit error, just re-run the same command. It picks up where it left off — each run indexes more files. With a large library (500+ papers) you may need to run it a few times.

After that, the index is cached at ~/.pqa/indexes/. Only new or changed files get re-processed on subsequent runs.

Related MCP server: Personal Research Assistant MCP

Troubleshooting

"Server disconnected" in Claude Desktop

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 so packages are cached.

"Index incomplete" when querying

The server checks the index before each query. If too many papers are unindexed, it returns a diagnostic message instead of trying (and failing) to index them all on the fly. Fix: run the index command in step 6.

Hammer icon doesn't appear

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.

Use a different LLM

By default, PaperQA2 uses gpt-4o-mini for its internal reasoning. This is separate from Claude — Claude calls the tool, PaperQA2 does its own LLM calls internally to gather and synthesize evidence.

To use a different model, add env vars to your Claude Desktop config:

"env": {
  "OPENAI_API_KEY": "sk-your-key-here",
  "PQA_LLM": "gpt-4o",
  "PQA_SUMMARY_LLM": "gpt-4o-mini"
}

All environment variables

Variable	Default	Purpose
`PAPER_DIRECTORY`	`~/Zotero/storage`	Folder containing your PDFs
`OPENAI_API_KEY`	—	Required for default embeddings
`PQA_LLM`	`gpt-4o-mini`	LLM for internal reasoning
`PQA_SUMMARY_LLM`	`gpt-4o-mini`	LLM for summarizing chunks
`PQA_EMBEDDING`	`text-embedding-3-small`	Embedding model
`ANTHROPIC_API_KEY`	—	Only if using Claude as internal LLM

Works with zotero-mcp

This pairs well with zotero-mcp:

paperqa-mcp-server — deep reading and synthesis across full paper text
zotero-mcp — browse your library, search metadata, read annotations

Claude can cross-reference between them — for example, finding papers with PaperQA and then pulling up their Zotero metadata and annotations. PaperQA2's citations include Zotero storage keys (e.g. ABC123DE from storage/ABC123DE/paper.pdf) that Claude can use to look up items via zotero-mcp.

Index implementation notes

paperqa-mcp-server index uses the same _settings() function as the MCP server, so the index it builds is exactly the one the server will look for. The PaperQA2 index directory name is a hash of the settings (embedding model, chunk size, paper directory path, etc.). The settings include:

Multimodal OFF — skip image extraction from PDFs (avoids a crash on PDFs with CMYK images)
Doc details OFF — skip Crossref/Semantic Scholar metadata lookups (avoids rate limits; Claude can get metadata from Zotero directly via zotero-mcp)
Concurrency 1 — index one file at a time to stay under OpenAI's embedding rate limit

Why not pqa index? The pqa CLI constructs settings via pydantic's CliSettingsSource, which produces different defaults than constructing Settings() directly in Python (e.g. chunk_chars of 7000 vs 5000). Different settings = different index hash = server can't find the index. Always use paperqa-mcp-server index to build the index.

Install from GitHub (latest)

To use the latest version from the main branch instead of PyPI:

{
  "mcpServers": {
    "paperqa": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["--from", "git+https://github.com/menyoung/paperqa-mcp-server", "paperqa-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

To build the index from the latest main branch:

OPENAI_API_KEY=sk-your-key-here uvx --from git+https://github.com/menyoung/paperqa-mcp-server paperqa-mcp-server index

Development

If you want to contribute or modify the server locally:

git clone https://github.com/menyoung/paperqa-mcp-server.git
cd paperqa-mcp-server
uv sync
uv run paperqa-mcp-server        # run the server
uv run paperqa-mcp-server index  # build the index

Available Tools

2 tools

index_statusA

Check the health of the paper index.

Returns a summary of how many papers are indexed, how many have errors, and how many are unindexed. Use this to diagnose why paper_qa queries might be failing or timing out.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It effectively discloses behavioral traits: it's a read-only diagnostic tool (implied by 'Check' and 'Returns'), and it specifies what information is returned (summary of indexed papers, errors, unindexed). However, it doesn't mention potential rate limits or authentication needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by usage guidance. Both sentences earn their place by providing essential information without redundancy, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no annotations, but has an output schema), the description is complete. It explains what the tool does, when to use it, and what it returns, which is sufficient since the output schema will handle return value details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema coverage, so the baseline is 4. The description appropriately doesn't add parameter details, as none are needed, and instead focuses on the tool's purpose and output.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Check the health', 'Returns a summary') and resources ('paper index'), distinguishing it from the sibling 'paper_qa' tool by focusing on diagnostic status rather than querying content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool ('to diagnose why paper_qa queries might be failing or timing out'), providing clear context and distinguishing it from the alternative sibling tool 'paper_qa'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

paper_qaA

Search and synthesize across all papers in the library.

Use this for questions that require deep reading and synthesis across multiple scientific papers — e.g. "What methods have been used to recycle lithium from spent batteries?" or "Compare the thermal stability of PEEK vs PTFE in the literature."

Returns a detailed answer with inline citations. Each citation includes a file path containing an 8-character Zotero storage key (e.g. ABC123DE from storage/ABC123DE/paper.pdf). You can use these keys with zotero-mcp tools to look up the full bibliographic record, read annotations, or find related items.

Not for quick metadata lookups or library browsing — use Zotero tools for that.

If this tool returns "Index incomplete", the paper index has not been fully built yet. Tell the user to run the index build command from the terminal (see the paperqa-mcp-server README, step 6). Do not retry the query — it will give the same result until the index is built.

This tool can take 30–90 seconds to respond when working normally.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool returns detailed answers with inline citations and specific file path formats, can return an 'Index incomplete' error with instructions for resolution, and has a long response time (30–90 seconds). It does not mention error handling beyond the index issue or rate limits, but covers essential operational aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines, output details, error handling, and performance notes. Each sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (synthesis across papers, citations, potential errors, long runtime) and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage, output format, error scenarios, and performance, providing all necessary context for effective tool invocation without needing to repeat schema details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 1 parameter with 0% description coverage, so the description must compensate. It implies the 'query' parameter is for complex research questions requiring synthesis, as shown in the examples, adding meaningful context beyond the schema's basic type definition. However, it does not specify format constraints or length limits for the query.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('search and synthesize') and resource ('across all papers in the library'), distinguishing it from sibling tools like 'index_status'. It provides concrete examples of appropriate queries, making the purpose unambiguous and well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly defines when to use this tool ('for questions that require deep reading and synthesis across multiple scientific papers') and when not to use it ('Not for quick metadata lookups or library browsing — use Zotero tools for that'). It also provides an alternative ('Zotero tools') for excluded use cases, offering comprehensive guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesv0.1.0Mar 18, 2026
- First observedindex_status
- First observedpaper_qa

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Disambiguation5/5

The two tools have completely distinct purposes with no overlap: index_status is for health/status monitoring of the indexing system, while paper_qa is for querying and synthesizing content across papers. Their descriptions clearly differentiate diagnostic vs. query functionality.

Naming Consistency5/5

Both tools follow a consistent snake_case naming pattern with clear verb_noun structure: index_status (verb: check/status, noun: index) and paper_qa (verb: query/answer, noun: paper). The naming is predictable and readable throughout.

Tool Count2/5

With only 2 tools, the server feels severely under-scoped for a paper query and synthesis domain. A typical paper/library server would need at least basic CRUD operations for papers, search filtering, or metadata management, but here the surface is minimal and relies heavily on external Zotero tools.

Completeness2/5

The toolset is incomplete for the apparent domain of paper querying and synthesis. There are no tools for managing papers (add/remove), browsing the library, filtering searches, or handling indexing beyond status checks. The server delegates core functionality to Zotero tools, creating significant gaps for agent workflows.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Rosetta PDF
io.github.Jcjimenezglez
Parse, extract, split, and ask over digital PDFs (text layer, no OCR) from Cursor and Claude.
File Systems Documentation Access AI & Machine Learning
1
PDFHaul MCP
com.pdfhaul.www
PDF tools for Claude: merge, split, compress, convert, OCR & more. Requires a PDFHaul API key.
File Systems Workplace & Productivity
2
Papertext
app.papertext.app
Academic literature search, retrieval, and private library management on top of OpenAlex.
Search Research & Data Knowledge & Memory
2
platform7nOAuth
tech.p7n
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
Communication Project Management Workplace & Productivity
2

Related MCP Servers

Claude RAG MCP Pipeline
RAG Systems Vector Databases Search
kenjisekino
A
license
Not graded
quality
D
maintenance
Enables Claude Desktop to search and query personal document collections (PDF, Word, Markdown, text) using semantic search and conversational AI with full context preservation across exchanges.
Updated a year ago (2025-09-20 18:06 UTC)
MIT
Personal Research Assistant
RAG Systems Vector Databases Search
chakri01
F
license
Not graded
quality
D
maintenance
Enables semantic search and conversational querying across a personal research library of PDFs, DOCX, and other documents using a vector database. It provides tools for document summarization, finding related papers, and high-accuracy retrieval for AI clients like Claude Desktop.
Updated 9 months ago (2025-12-09 05:14 UTC)
-
arXiv Reader MCP
Research & Data Search
YounesBensafia
A
license
A
quality
C
maintenance
Search and read arXiv papers directly from Claude. Supports keyword, author, category, and date filtering plus full PDF text extraction so Claude can read, summarise, and reason over entire papers, not just abstracts.
Updated 3 months ago (2026-06-07 18:13 UTC)
5
24
MIT
Metis
Knowledge & Memory RAG Systems Research & Data
SVerITG
A
license
A
quality
C
maintenance
A second brain for researchers — gives Claude persistent memory of your papers, field, and working history, with answers cited from your own indexed library
Updated a day ago (2026-09-05 10:33 UTC)
100
3
AGPL 3.0

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/menyoung/paperqa-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

paperqa-mcp-server

Quick start

1. Install uv

2. Get an OpenAI API key

3. Warm the package cache

4. Find your full path to uvx

5. Add to Claude Desktop

6. Pre-build the index

Troubleshooting

Use a different LLM

All environment variables

Works with zotero-mcp

Index implementation notes

Install from GitHub (latest)

Development

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Claude RAG MCP Pipeline

Personal Research Assistant

arXiv Reader MCP

Metis

Latest Blog Posts

MCP directory API