AI导哈

PDF语义问答服务

基于paperqa v5的MCP服务器，提供针对本地PDF论文的语义问答功能。

  • by KonstantinPakulev
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 KonstantinPakulev/paperqa-mcp

使用说明

paperqa mcp

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

工具

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

设置

需要Python 3.11+和 uv.

环境变量

变量 目的 默认值
PAPER_DIR 包含PDF的目录的绝对路径 必需
PAPERQA_LLM 主要LLM模型 claude-haiku-4-5-20251001
PAPERQA_SUMMARY_LLM LLM模型摘要 与 PAPERQA_LLM
PAPERQA_AGENT_LLM 代理LLM模型 与 PAPERQA_LLM
PAPERQA_EMBEDDING 嵌入模型 openrouter/openai/text-embedding-3-small
ANTHROPIC_API_KEY Anthropic API钥匙（适用于Claude车型） 克劳德需要
OPENROUTER_API_KEY OpenRouter API密钥（用于OpenRouter LLM和嵌入） OpenRouter需要
ZHIPUAI_API_KEY 智普AI API密钥（适用于z.AI/GLM型号） z.ai型号需要

支持的型号

拟人克劳德模型

  • 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/<model-id> -任何直接的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"

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

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

  3. 会话环境 （临时）：

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

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

相关 MCP