notion_retrieve_comments
Retrieve unresolved comments from Notion pages or blocks using block ID, with options for JSON or markdown formatting and pagination control.
Instructions
Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block or page whose comments you want to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
| page_size | No | Number of comments to retrieve (max 100). | |
| start_cursor | No | If supplied, returns a page of results starting after the cursor. |
Implementation Reference
- src/client/index.ts:271-290 (handler)Core implementation of the 'notion_retrieve_comments' tool logic in NotionClientWrapper class. Makes a GET request to Notion's /comments API endpoint with block_id and optional pagination parameters.async retrieveComments( block_id: string, start_cursor?: string, page_size?: number ): Promise<ListResponse> { const params = new URLSearchParams(); params.append("block_id", block_id); if (start_cursor) params.append("start_cursor", start_cursor); if (page_size) params.append("page_size", page_size.toString()); const response = await fetch( `${this.baseUrl}/comments?${params.toString()}`, { method: "GET", headers: this.headers, } ); return response.json(); }
- src/server/index.ts:237-249 (handler)Server-side dispatch handler for 'notion_retrieve_comments' tool in the CallToolRequest switch statement. Validates input and calls the client method.case "notion_retrieve_comments": { const args = request.params .arguments as unknown as args.RetrieveCommentsArgs; if (!args.block_id) { throw new Error("Missing required argument: block_id"); } response = await notionClient.retrieveComments( args.block_id, args.start_cursor, args.page_size ); break; }
- src/types/schemas.ts:398-424 (schema)Tool schema definition for 'notion_retrieve_comments', including name, description, and input schema validation.export const retrieveCommentsTool: Tool = { name: "notion_retrieve_comments", description: "Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.", inputSchema: { type: "object", properties: { block_id: { type: "string", description: "The ID of the block or page whose comments you want to retrieve." + commonIdDescription, }, start_cursor: { type: "string", description: "If supplied, returns a page of results starting after the cursor.", }, page_size: { type: "number", description: "Number of comments to retrieve (max 100).", }, format: formatParameter, }, required: ["block_id"], }, };
- src/server/index.ts:302-326 (registration)Registration of the 'notion_retrieve_comments' tool (as retrieveCommentsTool) in the MCP server's ListToolsRequest handler, making it available based on enabledToolsSet.server.setRequestHandler(ListToolsRequestSchema, async () => { const allTools = [ schemas.appendBlockChildrenTool, schemas.retrieveBlockTool, schemas.retrieveBlockChildrenTool, schemas.deleteBlockTool, schemas.updateBlockTool, schemas.retrievePageTool, schemas.updatePagePropertiesTool, schemas.listAllUsersTool, schemas.retrieveUserTool, schemas.retrieveBotUserTool, schemas.createDatabaseTool, schemas.queryDatabaseTool, schemas.retrieveDatabaseTool, schemas.updateDatabaseTool, schemas.createDatabaseItemTool, schemas.createCommentTool, schemas.retrieveCommentsTool, schemas.searchTool, ]; return { tools: filterTools(allTools, enabledToolsSet), }; });