notion_create_comment
Add comments to Notion pages or existing discussion threads using rich text formatting, including mentions, links, and equations.
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 |
|---|---|---|---|
| parent | No | Parent object that specifies the page to comment on. Must include a page_id if used. | |
| 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 (-). | |
| rich_text | Yes | Array of rich text objects representing the comment content. | |
| 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 |
Implementation Reference
- src/server/index.ts:234-250 (handler)Tool handler that processes notion_create_comment requests, validates that either parent.page_id or discussion_id is provided, and calls the NotionClient.createComment method with the parsed arguments.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:396-431 (schema)Tool schema definition for notion_create_comment, including name, description, and input schema with properties for parent (page_id), discussion_id, rich_text array, and optional format parameter.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:335-335 (registration)Tool registration where createCommentTool is added to the list of available MCP tools exposed by the server.schemas.createCommentTool,
- src/client/index.ts:285-305 (handler)Client implementation of createComment that constructs the API request body with optional parent and discussion_id, makes a POST request to the Notion /comments endpoint, and returns the CommentResponse.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/types/args.ts:120-125 (schema)TypeScript interface definition for CreateCommentArgs, specifying optional parent with page_id, optional discussion_id, required rich_text array, and optional format parameter.export interface CreateCommentArgs { parent?: { page_id: string }; discussion_id?: string; rich_text: RichTextItemResponse[]; format?: "json" | "markdown"; }