logseq_insert_block

Insert new blocks into Logseq to create page-level or nested blocks, manage properties, and set custom UUIDs. Specify positioning relative to parent blocks for precise organization and reference.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`before`	No	Insert before parent
`content`	Yes	Content of the new block
`custom_uuid`	No	Custom UUID for block
`is_page_block`	No	Page-level block flag
`parent_block`	No	UUID or content of parent block

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,
        ),
    ],

Logseq MCP Server