Paperqa MCP

paperqa mcp

MCP服务器包装 paperqa v5 用于本地PDF论文的语义问答。

工具

• ask_question(question) --从索引的PDF中回答一个研究问题，并附上引用。
• list_papers() --在纸张目录中列出PDF文件，并报告索引状态。

设置

需要Python 3.11+和 uv.

环境变量

支持的型号

拟人克劳德模型

• claude-haiku-4-5-20251001 （默认）
• claude-opus-4-6
• claude-sonnet-4-6

z.ai（智普ai）模型

• openai/glm-4 -最新的复杂任务
• openai/glm-4.7 -增强编码，长任务
• openai/glm-4.7-FlashX -重量轻，速度快
• openai/glm-4.6 -编码专家（使用编码API端点）
• openai/glm-4.5-air -成本效益高

备注：z.ai型号需要 ZHIPUAI_API_KEY 待设定。服务器自动使用相应的API端点(/api/paas/v4/ 或 /api/coding/paas/v4/)基于该模型。

OpenRouter型号

• openrouter/free -OpenRouter免费型号路由器
• openrouter/ -任何直接的OpenRouter型号ID，包括 :free 变体

备注：OpenRouter型号需要 OPENROUTER_API_KEY聊天模型支持内置于此MCP包装器中，但PaperQA依赖于代理/工具调用行为，一些免费的OpenRouter路由可能仍与当前的不兼容 paperqa/LiteLLM堆栈。将免费变体视为实验性的，并在将其设置为默认值之前对其进行测试。

跑步

uv run --python 3.11 --project /path/to/paperqa-mcp paperqa-mcp

MCP配置(.mcp.json)

默认配置（Claude Haiku）

"paperqa": {
  "command": "uv",
  "args": [
    "run",
    "--python", "3.11",
    "--project", "/path/to/paperqa-mcp",
    "paperqa-mcp"
  ],
  "env": {
    "PAPER_DIR": "/path/to/paper/references"
  }
}

使用z.ai GLM-4.6（编码专家）

"paperqa": {
  "command": "uv",
  "args": [
    "run",
    "--python", "3.11",
    "--project", "/path/to/paperqa-mcp",
    "paperqa-mcp"
  ],
  "env": {
    "PAPER_DIR": "/path/to/paper/references",
    "PAPERQA_LLM": "openai/glm-4.6",
    "PAPERQA_SUMMARY_LLM": "openai/glm-4.6",
    "PAPERQA_AGENT_LLM": "openai/glm-4.6"
  }
}

使用OpenRouter免费型号

"paperqa": {
  "command": "uv",
  "args": [
    "run",
    "--python", "3.11",
    "--project", "/path/to/paperqa-mcp",
    "paperqa-mcp"
  ],
  "env": {
    "PAPER_DIR": "/path/to/paper/references",
    "PAPERQA_LLM": "openrouter/free",
    "PAPERQA_SUMMARY_LLM": "openrouter/free",
    "PAPERQA_AGENT_LLM": "openrouter/free",
    "PAPERQA_EMBEDDING": "openrouter/openai/text-embedding-3-small"
  }
}

如果 ask_question() 特定于OpenRouter失败 tool_choice, tool use或提供程序路由错误，切换到不同的OpenRouter模型或回退到代理LLM的非自由模型/提供程序。

混合配置（不同任务的不同LLM）

"paperqa": {
  "command": "uv",
  "args": [
    "run",
    "--python", "3.11",
    "--project", "/path/to/paperqa-mcp",
    "paperqa-mcp"
  ],
  "env": {
    "PAPER_DIR": "/path/to/paper/references",
    "PAPERQA_LLM": "openai/glm-4",
    "PAPERQA_SUMMARY_LLM": "claude-haiku-4-5-20251001",
    "PAPERQA_AGENT_LLM": "openai/glm-4.6"
  }
}

API密钥管理

重要：The .mcp.json 文件不支持shell变量扩展（例如。， $API_KEY).API密钥必须从shell环境继承。

设置API密钥

您可以通过以下方式之一设置API密钥：

1. 外壳外形 （建议用于持久设置）：

   # Add to ~/.bashrc or ~/.zshrc
   export ANTHROPIC_API_KEY="your-anthropic-key"
   export OPENROUTER_API_KEY="your-openrouter-key"
   export ZHIPUAI_API_KEY="your-zhipuai-key"

1. 项目 .env 文件 （适用于基于Docker的工作流）：

   # Add to .env (gitignored)
   ANTHROPIC_API_KEY=your-anthropic-key
   OPENROUTER_API_KEY=your-openrouter-key
   ZHIPUAI_API_KEY=your-zhipuai-key

1. 会话环境 （临时）：

   export OPENROUTER_API_KEY="your-openrouter-key" && claude-code

MCP服务器在启动时会自动继承这些环境变量。