paperqa-mcp-server

Instructions

Implementation Reference

• src/paperqa_mcp_server/__init__.py:121-159 (handler)

  The 'paper_qa' tool handler is defined using @mcp.tool() in src/paperqa_mcp_server/__init__.py. It validates the index status before performing an agent_query using the paperqa library.

  @mcp.tool()
  async def paper_qa(query: str) -> str:
      """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.
      """
      settings = _settings()
      status = _index_status(settings)
      if not status["ready"]:
          return f"Index incomplete: {status['message']}"
  
      try:
          response = await agent_query(query=query, settings=settings)
      except Exception as e:
          return f"PaperQA error: {e}"
      if not response.session.formatted_answer:
          return f"PaperQA could not answer (status: {response.status})."
      return response.session.formatted_answer