Zotero MCP

Instructions

Implementation Reference

• src/zotero_mcp/server.py:463-530 (handler)

  The main handler function for the 'zotero_get_collection_items' tool. It fetches items from a specified Zotero collection using the pyzotero client, formats them into a markdown list with title, type, key, date, and authors, and handles errors gracefully.

  @mcp.tool(
      name="zotero_get_collection_items",
      description="Get all items in a specific Zotero collection."
  )
  def get_collection_items(
      collection_key: str,
      limit: Optional[Union[int, str]] = 50,
      *,
      ctx: Context
  ) -> str:
      """
      Get all items in a specific Zotero collection.
      
      Args:
          collection_key: The collection key/ID
          limit: Maximum number of items to return
          ctx: MCP context
      
      Returns:
          Markdown-formatted list of items in the collection
      """
      try:
          ctx.info(f"Fetching items for collection {collection_key}")
          zot = get_zotero_client()
          
          # First get the collection details
          try:
              collection = zot.collection(collection_key)
              collection_name = collection["data"].get("name", "Unnamed Collection")
          except Exception:
              collection_name = f"Collection {collection_key}"
          
          if isinstance(limit, str):
              limit = int(limit)
          
          # Then get the items
          items = zot.collection_items(collection_key, limit=limit)
          if not items:
              return f"No items found in collection: {collection_name} (Key: {collection_key})"
          
          # Format items as markdown
          output = [f"# Items in Collection: {collection_name}", ""]
          
          for i, item in enumerate(items, 1):
              data = item.get("data", {})
              title = data.get("title", "Untitled")
              item_type = data.get("itemType", "unknown")
              date = data.get("date", "No date")
              key = item.get("key", "")
              
              # Format creators
              creators = data.get("creators", [])
              creators_str = format_creators(creators)
              
              # Build the formatted entry
              output.append(f"## {i}. {title}")
              output.append(f"**Type:** {item_type}")
              output.append(f"**Item Key:** {key}")
              output.append(f"**Date:** {date}")
              output.append(f"**Authors:** {creators_str}")
              
              output.append("")  # Empty line between items
          
          return "\n".join(output)
      
      except Exception as e:
          ctx.error(f"Error fetching collection items: {str(e)}")
          return f"Error fetching collection items: {str(e)}"