Notion MCP Server

Instructions

Implementation Reference

• server.js:350-373 (handler)

  Handler for the 'query-database' tool. Destructures arguments, builds query parameters for Notion's databases.query API (including optional filter, sorts, pagination), calls the API, and returns the response as text content.
  else if (name === "query-database") { console.error("Query database handler called with:", JSON.stringify(args, null, 2)); const { database_id, filter, sorts, start_cursor, page_size } = args; const queryParams = { database_id, page_size: page_size || 100, }; if (filter) queryParams.filter = filter; if (sorts) queryParams.sorts = sorts; if (start_cursor) queryParams.start_cursor = start_cursor; const response = await notion.databases.query(queryParams); return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; }
• server.js:51-80 (schema)

  Tool definition in tools/list response, including name, description, and detailed inputSchema specifying parameters for querying a Notion database.
  name: "query-database", description: "Query a database", inputSchema: { type: "object", properties: { database_id: { type: "string", description: "ID of the database to query" }, filter: { type: "object", description: "Optional filter criteria" }, sorts: { type: "array", description: "Optional sort criteria" }, start_cursor: { type: "string", description: "Optional cursor for pagination" }, page_size: { type: "number", description: "Number of results per page", default: 100 } }, required: ["database_id"] } },
• server.js:37-313 (registration)

  The tools/list request handler that registers/declares all available tools including 'query-database' with their schemas.
  server.setRequestHandler(z.object({ method: z.literal("tools/list") }), async () => { return { tools: [ { name: "list-databases", description: "List all databases the integration has access to", inputSchema: { type: "object", properties: {} } }, { name: "query-database", description: "Query a database", inputSchema: { type: "object", properties: { database_id: { type: "string", description: "ID of the database to query" }, filter: { type: "object", description: "Optional filter criteria" }, sorts: { type: "array", description: "Optional sort criteria" }, start_cursor: { type: "string", description: "Optional cursor for pagination" }, page_size: { type: "number", description: "Number of results per page", default: 100 } }, required: ["database_id"] } }, { name: "create-page", description: "Create a new page in a database", inputSchema: { type: "object", properties: { parent_id: { type: "string", description: "ID of the parent database" }, properties: { type: "object", description: "Page properties" }, children: { type: "array", description: "Optional content blocks" } }, required: ["parent_id", "properties"] } }, { name: "update-page", description: "Update an existing page", inputSchema: { type: "object", properties: { page_id: { type: "string", description: "ID of the page to update" }, properties: { type: "object", description: "Updated page properties" }, archived: { type: "boolean", description: "Whether to archive the page" } }, required: ["page_id", "properties"] } }, { name: "create-database", description: "Create a new database", inputSchema: { type: "object", properties: { parent_id: { type: "string", description: "ID of the parent page" }, title: { type: "array", description: "Database title as rich text array" }, properties: { type: "object", description: "Database properties schema" }, icon: { type: "object", description: "Optional icon for the database" }, cover: { type: "object", description: "Optional cover for the database" } }, required: ["parent_id", "title", "properties"] } }, { name: "update-database", description: "Update an existing database", inputSchema: { type: "object", properties: { database_id: { type: "string", description: "ID of the database to update" }, title: { type: "array", description: "Optional new title as rich text array" }, description: { type: "array", description: "Optional new description as rich text array" }, properties: { type: "object", description: "Optional updated properties schema" } }, required: ["database_id"] } }, { name: "get-page", description: "Retrieve a page by its ID", inputSchema: { type: "object", properties: { page_id: { type: "string", description: "ID of the page to retrieve" } }, required: ["page_id"] } }, { name: "get-block-children", description: "Retrieve the children blocks of a block", inputSchema: { type: "object", properties: { block_id: { type: "string", description: "ID of the block (page or block)" }, start_cursor: { type: "string", description: "Cursor for pagination" }, page_size: { type: "number", description: "Number of results per page", default: 100 } }, required: ["block_id"] } }, { name: "append-block-children", description: "Append blocks to a parent block", inputSchema: { type: "object", properties: { block_id: { type: "string", description: "ID of the parent block (page or block)" }, children: { type: "array", description: "List of block objects to append" }, after: { type: "string", description: "Optional ID of an existing block to append after" } }, required: ["block_id", "children"] } }, { name: "update-block", description: "Update a block's content or archive status", inputSchema: { type: "object", properties: { block_id: { type: "string", description: "ID of the block to update" }, block_type: { type: "string", description: "The type of block (paragraph, heading_1, to_do, etc.)" }, content: { type: "object", description: "The content for the block based on its type" }, archived: { type: "boolean", description: "Whether to archive (true) or restore (false) the block" } }, required: ["block_id", "block_type", "content"] } }, { name: "get-block", description: "Retrieve a block by its ID", inputSchema: { type: "object", properties: { block_id: { type: "string", description: "ID of the block to retrieve" } }, required: ["block_id"] } }, { name: "search", description: "Search Notion for pages or databases", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query string", default: "" }, filter: { type: "object", description: "Optional filter criteria" }, sort: { type: "object", description: "Optional sort criteria" }, start_cursor: { type: "string", description: "Cursor for pagination" }, page_size: { type: "number", description: "Number of results per page", default: 100 } } } } ] }; });