Paperqa MCP Server

paperqa mcp服务器

让克劳德能够阅读、搜索和综合你的 整个PDF库。建立在 纸张QA2.

将其指向您的Zotero存储文件夹（或任何PDF文件夹）并询问 克劳德的问题需要在多篇论文中深入阅读。

快速开始

1.安装uv

紫外线 是一个Python包管理器。如果你不 还没有：

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

安装后， 重新启动终端 所以 uv 在你的路径上。

验证它是否有效：

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.添加到克劳德桌面

1. 打开克劳德桌面
2. 首选 设置→ 开发者→ 编辑配置
3. 这将打开 claude_desktop_config.json.添加a paperqa 进入里面

mcpServers （创建 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 --粘贴输出 which uvx 从步骤4开始
• sk-your-key-here -步骤2中的OpenAI API密钥

如果您的PDF文件不在其他地方 ~/Zotero/storage，添加a PAPER_DIRECTORY 进入 env:

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

1. 完全退出克劳德桌面 （Cmd+Q，不仅仅是关闭窗口）

并重新打开它

1. 你应该看到一个锤子图标——点击它 paper_qa 应列出

6.预先构建索引

在克劳德搜索你的论文之前，服务器需要建立一个搜索 指数。这将读取每个PDF，将其拆分为块，并发送块 到OpenAI的嵌入API。有数百篇论文，这需要一段时间 并且在API调用中花费几美元。

如果你有超过10篇未编入索引的论文，服务器将拒绝 回答查询并告诉您先运行此步骤。几篇新论文 查询时将自动索引。

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

在处理每篇论文时，您将看到日志行。当它完成时，它 打印 Done.

如果这崩溃了 如果出现速率限制错误，只需重新运行相同的命令。 它从停止的地方继续——每次运行都会索引更多的文件。与一个大 图书馆（500多篇论文），你可能需要运行几次。

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

故障排除

Claude Desktop中的“服务器已断开连接”

Claude Desktop的启动超时时间很短。如果 uv 需要下载 首次发布时，它将超时。修复：运行 uvx paperqa-mcp-server 首先从终端发送一次，以便缓存包。

查询时“索引不完整”

服务器在每次查询之前检查索引。如果纸张太多 如果没有索引，它将返回诊断消息，而不是尝试（和 未能及时将它们全部编入索引。修复：在中运行index命令 步骤6。

锤子图标未出现

确保您完全退出Claude Desktop（Cmd+Q）并重新打开它。 检查中的JSON语法错误 claude_desktop_config.json 一 缺少逗号是最常见的错误。

使用不同的LLM

默认情况下，PaperQA2使用 gpt-4o-mini 因为它的内在推理。 这与Claude是分开的——Claude调用该工具，PaperQA2调用 它自己的法学硕士在内部呼吁收集和综合证据。

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

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

所有环境变量

与zotero mcp合作

这与 佐特罗mcp:

• paperqa mcp服务器 --全文深度阅读与综合
• 佐特罗mcp --浏览您的库、搜索元数据、阅读注释

克劳德可以在它们之间进行交叉引用——例如，查找论文 使用PaperQA，然后提取他们的Zotero元数据和注释。 PaperQA2的引用包括Zotero存储密钥（例如。 ABC123DE 从 storage/ABC123DE/paper.pdf)克劳德可以通过以下方式查找项目 佐特罗mcp。

索引实施说明

paperqa-mcp-server index 使用相同 _settings() 充当MCP 服务器，因此它构建的索引正是服务器将查看的索引 为。PaperQA2索引目录名称是设置的哈希值 （嵌入模型、块大小、纸张目录路径等）。设置 包括：

• 多模式关闭 --跳过PDF中的图像提取（避免崩溃

带有CMYK图像的PDF）

• 文档详细信息关闭 --跳过Crossref/语义学者元数据查找

（避免了速率限制；Claude可以直接通过以下方式从Zotero获取元数据 佐特罗mcp）

• 并发1 --一次索引一个文件，以保持在OpenAI的

嵌入速率限制

为什么不 pqa index? 这 pqa CLI通过pydantic构建设置 CliSettingsSource，这会产生与构造不同的默认值 Settings() 直接在Python中（例如。 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