Logseq MCP Tools

Instructions

Searches for blocks matching a query in the Logseq graph.

Examples of useful queries:
- page:"Page Name" - find all blocks on a specific page
- "search term" - find blocks containing the term
- page:"Apr 4th, 2025" - find all blocks in a journal
- [[Page Name]] - find references to a specific page

Returned blocks from journal pages will include:
- "journal?": true
- "journalDay": YYYYMMDD - The date in numeric format

Args:
    query (str): The search query.
    
Returns:
    list: A list of blocks matching the search query.

Implementation Reference

• src/logseq_mcp/tools/blocks.py:181-203 (handler)

  The main handler function for the MCP 'search_blocks' tool. Decorated with @mcp.tool() which registers it automatically with the FastMCP server. This thin wrapper delegates to the LogseqClient's search_blocks method.

  @mcp.tool()
  def search_blocks(query: str) -> List[Dict]:
      """
      Searches for blocks matching a query in the Logseq graph.
      
      Examples of useful queries:
      - page:"Page Name" - find all blocks on a specific page
      - "search term" - find blocks containing the term
      - page:"Apr 4th, 2025" - find all blocks in a journal
      - [[Page Name]] - find references to a specific page
      
      Returned blocks from journal pages will include:
      - "journal?": true
      - "journalDay": YYYYMMDD - The date in numeric format
      
      Args:
          query (str): The search query.
          
      Returns:
          list: A list of blocks matching the search query.
      """
      """Search for blocks matching the query."""
      return logseq_client.search_blocks(query)

• src/logseq_mcp/client/logseq_client.py:100-105 (helper)

  The underlying helper method in LogseqAPIClient that performs the actual API call to Logseq's 'logseq.Editor.search' endpoint, handling response normalization.

  def search_blocks(self, query: str) -> List[Dict]:
      """Search for blocks matching a query"""
      response = self.call_api("logseq.Editor.search", [query])
      if isinstance(response, list):
          return response
      return response.get("result", []) if isinstance(response, dict) else []

• src/logseq_mcp/__init__.py:17-18 (registration)

  The tool is exported and made available for import in the package __init__.py, ensuring it's registered when the server module is imported and run.

  __all__ = ["get_all_pages", "get_page", "create_page", "get_page_blocks", "get_block", "create_block", "update_block", "search_blocks", "get_page_linked_references"]

• src/logseq_mcp/tools/__init__.py:16-16 (registration)

  Exported in tools/__init__.py __all__, which propagates to main __init__.py.

  "search_blocks",