paperqa-mcp-server

paperqa-mcp-server

让 Claude 能够阅读、搜索并综合整个 PDF 文献库中的内容。基于 PaperQA2 构建。

将其指向你的 Zotero 存储文件夹（或任何存放 PDF 的文件夹），然后向 Claude 提出需要深入阅读多篇论文才能回答的问题。

快速开始

1. 安装 uv

uv 是一款 Python 包管理器。如果你还没有安装：

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

安装后，重启终端，让 uv 加入 PATH。

验证是否正常运行：

uv --version

2. 获取 OpenAI API 密钥

PaperQA2 使用 OpenAI 进行嵌入和内部推理。请在以下网址获取密钥： https://platform.openai.com/api-keys

3. 预热软件包缓存

首次运行时会下载约 90 个 Python 软件包，这是正常现象，只会发生一次。运行以下命令，先缓存软件包，再让 Claude Desktop 尝试启动服务：

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

你应该会看到类似 Building index: ... 的输出。按 Ctrl+C 停止（我们会在第 6 步构建正式索引）。如果看到的是 Python 错误，则说明安装过程中出了问题。

4. 查找 uvx 的完整路径

Claude Desktop 无法自行找到 uvx，因此你需要提供它的完整路径。运行：

which uvx

这会输出类似 /Users/yourname/.local/bin/uvx 的内容。复制该路径——下一步会用到。

5. 添加到 Claude Desktop

1. 打开 Claude Desktop
2. 前往 Settings → Developer → Edit Config
3. 这会打开 claude_desktop_config.json。在 mcpServers 中添加 paperqa 条目（如果 mcpServers 不存在，则创建它）：

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

替换两个占位内容：

• /Users/yourname/.local/bin/uvx — 粘贴第 4 步中 which uvx 的输出
• sk-your-key-here — 粘贴第 2 步获取的 OpenAI API 密钥

如果你的 PDF 存放在 ~/Zotero/storage 以外的位置，请在 env 中添加 PAPER_DIRECTORY 条目：

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

4. 完全退出 Claude Desktop（按 Cmd+Q，而不只是关闭窗口），然后重新打开
5. 你应该会看到一个锤子图标——点击它，确认列表中出现 paper_qa

6. 预先构建索引

Claude 要搜索你的论文，服务需要先构建搜索索引。它会读取每个 PDF，将内容拆分成文本块，并将这些文本块发送到 OpenAI 的嵌入 API。处理数百篇论文需要一些时间，并会产生几美元的 API 调用费用。

如果有超过 10 篇未编入索引的论文，服务会拒绝回答查询，并提示你先运行此步骤。查询时会自动为少量新论文编制索引。

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

每处理一篇论文，你都会看到相应的日志行。处理完成后会输出 Done.

如果此步骤因速率限制错误而崩溃，只需重新运行相同的命令。它会从上次中断处继续——每次运行都会为更多文件编制索引。对于大型文献库（500 篇以上论文），你可能需要运行几次。

之后，索引会缓存在 ~/.pqa/indexes/。后续运行时，只会重新处理新增或已更改的文件。

故障排除

Claude Desktop 中显示“Server disconnected”

Claude Desktop 的启动超时时间较短。如果 uv 在首次启动时需要下载软件包，就会超时。解决方法：先在终端中运行一次 uvx paperqa-mcp-server，以缓存软件包。

查询时显示“Index incomplete”

服务会在每次查询前检查索引。如果未编入索引的论文过多，它会返回诊断消息，而不是尝试一次性为它们全部编制索引（并最终失败）。解决方法：运行第 6 步中的索引命令。

没有出现锤子图标

确保完全退出 Claude Desktop（按 Cmd+Q）并重新打开。检查 claude_desktop_config.json 中是否存在 JSON 语法错误——最常见的问题是缺少逗号。

使用其他 LLM

默认情况下，PaperQA2 使用 gpt-4o-mini 进行内部推理。 这与 Claude 是分开的——Claude 调用工具，而 PaperQA2 会在内部自行调用 LLM 来收集和综合证据。

若要使用其他模型，请在 Claude Desktop 配置中添加环境变量：

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

所有环境变量

变量	默认值	用途
PAPER_DIRECTORY	~/Zotero/storage	存放 PDF 的文件夹
OPENAI_API_KEY	—	使用默认嵌入模型时必需
PQA_LLM	gpt-4o-mini	用于内部推理的大模型
PQA_SUMMARY_LLM	gpt-4o-mini	用于总结文本块的大模型
PQA_EMBEDDING	text-embedding-3-small	嵌入模型
ANTHROPIC_API_KEY	—	仅在使用 Claude 作为内部大模型时需要

与 zotero-mcp 配合使用

它与 zotero-mcp 搭配效果很好：

• paperqa-mcp-server — 深入阅读并综合整篇论文的内容
• zotero-mcp — 浏览文献库、搜索元数据、阅读批注

Claude 可以在两者之间交叉引用——例如，使用 PaperQA 查找论文， 然后调取其 Zotero 元数据和批注。PaperQA2 的引文包含 Zotero 存储键（例如， storage/ABC123DE/paper.pdf 中的 ABC123DE），Claude 可以使用该键 通过 zotero-mcp 查找条目。

索引实现说明

paperqa-mcp-server index 使用与 MCP 服务相同的 _settings() 函数， 因此它构建的索引正是服务会查找的索引。PaperQA2 索引目录名称是根据设置 （嵌入模型、文本块大小、论文目录路径等）生成的哈希值。设置包括：

• 关闭多模态 — 跳过从 PDF 中提取图像（避免处理包含 CMYK 图像的 PDF 时崩溃）
• 关闭文档详情 — 跳过 Crossref/Semantic Scholar 元数据查询 （避免触发速率限制；Claude 可以直接通过 zotero-mcp 从 Zotero 获取元数据）
• 并发数为 1 — 一次为一个文件建立索引，以避免超过 OpenAI 的 嵌入速率限制

为什么不使用 pqa index？ pqa CLI 通过 pydantic 的 CliSettingsSource 构造设置，与直接在 Python 中构造 Settings() 得到的默认值不同（例如，chunk_chars 分别为 7000 和 5000）。 设置不同 = 索引哈希值不同 = 服务无法找到索引。 始终使用 paperqa-mcp-server index 构建索引。

从 GitHub 安装（最新版本）

若要使用主分支中的最新版本，而非 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"
      }
    }
  }
}

若要使用最新主分支构建索引：

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

开发

如果你想为服务做贡献或在本地修改它：

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