Logseq MCP Server

Instructions

Implementation Reference

• src/mcp_server_logseq/server.py:464-481 (handler)

  Handler implementation within @server.call_tool(): parses InsertBlockParams, calls Logseq API method 'logseq.Editor.insertBlock' with parameters, formats and returns the result as TextContent.

  if name == "logseq_insert_block":
      args = InsertBlockParams(**arguments)
      result = make_request(
          "logseq.Editor.insertBlock",
          [
              args.parent_block,
              args.content,
              {
                  "isPageBlock": args.is_page_block,
                  "before": args.before,
                  "customUUID": args.custom_uuid
              }
          ]
      )
      return [TextContent(
          type="text",
          text=format_block_result(result)
      )]

• src/mcp_server_logseq/server.py:26-57 (schema)

  Pydantic model defining input schema for logseq_insert_block tool with fields: parent_block, content, is_page_block, before, custom_uuid, including validator for block references.

  class InsertBlockParams(LogseqBaseModel):
      """Parameters for inserting a new block in Logseq."""
      parent_block: Annotated[
          Optional[str],
          Field(default=None, description="UUID or content of parent block")
      ]
      content: Annotated[
          str,
          Field(description="Content of the new block")
      ]
      is_page_block: Annotated[
          Optional[bool],
          Field(default=False, description="Page-level block flag")
      ]
      before: Annotated[
          Optional[bool],
          Field(default=False, description="Insert before parent")
      ]
      custom_uuid: Annotated[
          Optional[str],
          Field(default=None, description="Custom UUID for block")
      ]
  
      @field_validator('parent_block', 'custom_uuid', mode='before')
      @classmethod
      def validate_block_references(cls, value):
          """Validate block/page references"""
          if value and isinstance(value, str):
              if value.startswith('((') and value.endswith('))'):
                  return value.strip('()')
          return value

• src/mcp_server_logseq/server.py:218-226 (registration)

  Tool registration in @server.list_tools() defining name, description, and inputSchema from InsertBlockParams.

  Tool(
      name="logseq_insert_block",
      description="""Insert a new block into Logseq. Can create:
      - Page-level blocks (use is_page_block=true with page name as parent_block)
      - Nested blocks under existing blocks
      - Blocks with custom UUIDs for precise reference
      Supports before/after positioning and property management.""",
      inputSchema=InsertBlockParams.model_json_schema(),
  ),

• src/mcp_server_logseq/server.py:397-404 (helper)

  Helper function to format the result of block insertion into a readable string used in handler response.

  def format_block_result(result: dict) -> str:
      """Format block creation result into readable text."""
      return (
          f"Created block in {result.get('page', {}).get('name', 'unknown page')}\n"
          f"UUID: {result.get('uuid')}\n"
          f"Content: {result.get('content')}\n"
          f"Parent: {result.get('parent', {}).get('uuid') or 'None'}"
      )

• src/mcp_server_logseq/server.py:283-302 (registration)

  Prompt registration in @server.list_prompts() for logseq_insert_block with argument definitions.

  Prompt(
      name="logseq_insert_block",
      description="Create a new block in Logseq",
      arguments=[
          PromptArgument(
              name="parent_block",
              description="Parent block UUID or page name (for page blocks)",
              required=False,
          ),
          PromptArgument(
              name="content",
              description="Block content in Markdown/Org syntax",
              required=True,
          ),
          PromptArgument(
              name="is_page_block",
              description="Set true for page-level blocks",
              required=False,
          ),
      ],