notion_retrieve_comments
Fetch unresolved comments from a Notion page or block using the block ID. Choose between JSON for modification or Markdown for readability to streamline comment management.
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 in NotionClientWrapper. Makes the GET request to Notion's /comments endpoint with block_id and pagination params.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)MCP server CallToolRequest handler case for notion_retrieve_comments. Validates input and delegates to NotionClientWrapper.retrieveComments.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 input schema and description.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 notion_retrieve_comments tool via inclusion of retrieveCommentsTool in the ListTools response.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), }; });
- src/types/args.ts:120-125 (helper)Type definition for arguments used in the handler.export interface RetrieveCommentsArgs { block_id: string; start_cursor?: string; page_size?: number; format?: "json" | "markdown"; }