notion_query_database
Retrieve and filter database entries from Notion using custom queries, sorting, and pagination to access organized information.
Instructions
Query a database in Notion
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to query.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| filter | No | Filter conditions | |
| 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 results per page (max 100) | |
| sorts | No | Sort conditions | |
| start_cursor | No | Pagination cursor for next page of results |
Implementation Reference
- src/client/index.ts:173-200 (handler)Core handler function in NotionClientWrapper that executes the Notion API /databases/{id}/query POST request with provided filter, sorts, pagination parameters.async queryDatabase( database_id: string, filter?: Record<string, any>, sorts?: Array<{ property?: string; timestamp?: string; direction: "ascending" | "descending"; }>, start_cursor?: string, page_size?: number ): Promise<ListResponse> { const body: Record<string, any> = {}; if (filter) body.filter = filter; if (sorts) body.sorts = sorts; if (start_cursor) body.start_cursor = start_cursor; if (page_size) body.page_size = page_size; const response = await fetch( `${this.baseUrl}/databases/${database_id}/query`, { method: "POST", headers: this.headers, body: JSON.stringify(body), } ); return response.json(); }
- src/types/schemas.ts:244-286 (schema)Tool schema definition including name, description, and inputSchema for notion_query_database.export const queryDatabaseTool: Tool = { name: "notion_query_database", description: "Query a database in Notion", inputSchema: { type: "object", properties: { database_id: { type: "string", description: "The ID of the database to query." + commonIdDescription, }, filter: { type: "object", description: "Filter conditions", }, sorts: { type: "array", description: "Sort conditions", items: { type: "object", properties: { property: { type: "string" }, timestamp: { type: "string" }, direction: { type: "string", enum: ["ascending", "descending"], }, }, required: ["direction"], }, }, start_cursor: { type: "string", description: "Pagination cursor for next page of results", }, page_size: { type: "number", description: "Number of results per page (max 100)", }, format: formatParameter, }, required: ["database_id"], }, };
- src/server/index.ts:302-326 (registration)Registration of all tools including notion_query_database schema in the MCP listTools handler.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/server/index.ts:163-176 (handler)MCP server CallToolRequest handler switch case that validates arguments and delegates to NotionClientWrapper.queryDatabase.case "notion_query_database": { const args = request.params .arguments as unknown as args.QueryDatabaseArgs; if (!args.database_id) { throw new Error("Missing required argument: database_id"); } response = await notionClient.queryDatabase( args.database_id, args.filter, args.sorts, args.start_cursor, args.page_size ); break;
- src/types/args.ts:80-91 (schema)TypeScript interface defining the argument types for notion_query_database tool.export interface QueryDatabaseArgs { database_id: string; filter?: Record<string, any>; sorts?: Array<{ property?: string; timestamp?: string; direction: "ascending" | "descending"; }>; start_cursor?: string; page_size?: number; format?: "json" | "markdown"; }