notion_create_comment
Add comments to Notion pages or discussion threads using rich text formatting, mentions, and equations to facilitate collaboration and feedback.
Instructions
Create a comment in Notion. This requires the integration to have 'insert comment' capabilities. You can either specify a page parent or a discussion_id, but not both.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| discussion_id | No | The ID of an existing discussion thread to add a comment to.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 |
| parent | No | Parent object that specifies the page to comment on. Must include a page_id if used. | |
| rich_text | Yes | Array of rich text objects representing the comment content. |
Implementation Reference
- src/client/index.ts:249-269 (handler)Core handler function in NotionClientWrapper that executes the Notion API call to create a comment (POST /comments). Constructs the request body from parent, discussion_id, or rich_text and sends the fetch request.async createComment( parent?: { page_id: string }, discussion_id?: string, rich_text?: RichTextItemResponse[] ): Promise<CommentResponse> { const body: Record<string, any> = { rich_text }; if (parent) { body.parent = parent; } if (discussion_id) { body.discussion_id = discussion_id; } const response = await fetch(`${this.baseUrl}/comments`, { method: "POST", headers: this.headers, body: JSON.stringify(body), }); return response.json(); }
- src/server/index.ts:219-235 (handler)Server-side dispatch handler for the tool: casts arguments to CreateCommentArgs, validates presence of parent or discussion_id, and invokes the client.createComment method.case "notion_create_comment": { const args = request.params .arguments as unknown as args.CreateCommentArgs; if (!args.parent && !args.discussion_id) { throw new Error( "Either parent.page_id or discussion_id must be provided" ); } response = await notionClient.createComment( args.parent, args.discussion_id, args.rich_text ); break; }
- src/types/schemas.ts:361-396 (schema)Tool schema definition including name, description, and inputSchema for validating notion_create_comment tool calls.export const createCommentTool: Tool = { name: "notion_create_comment", description: "Create a comment in Notion. This requires the integration to have 'insert comment' capabilities. You can either specify a page parent or a discussion_id, but not both.", inputSchema: { type: "object", properties: { parent: { type: "object", description: "Parent object that specifies the page to comment on. Must include a page_id if used.", properties: { page_id: { type: "string", description: "The ID of the page to comment on." + commonIdDescription, }, }, }, discussion_id: { type: "string", description: "The ID of an existing discussion thread to add a comment to." + commonIdDescription, }, rich_text: { type: "array", description: "Array of rich text objects representing the comment content.", items: richTextObjectSchema, }, format: formatParameter, }, required: ["rich_text"], }, };
- src/server/index.ts:302-326 (registration)Registers the createCommentTool schema in the list of available tools returned by ListToolsRequestHandler, enabling the tool for MCP clients.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:113-118 (helper)TypeScript interface for type-casting tool arguments in the server handler.export interface CreateCommentArgs { parent?: { page_id: string }; discussion_id?: string; rich_text: RichTextItemResponse[]; format?: "json" | "markdown"; }