notion_query_database
Retrieve and filter data from Notion databases using queries, sorting, and pagination to access structured 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 | |
| sorts | No | Sort conditions | |
| start_cursor | No | Pagination cursor for next page of results | |
| page_size | No | Number of results per page (max 100) | |
| 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/client/index.ts:173-200 (handler)Core implementation of the notion_query_database tool: makes POST request to Notion API /databases/{database_id}/query with optional filter, sorts, pagination.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/server/index.ts:163-176 (handler)MCP server handler for notion_query_database: validates database_id 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/schemas.ts:244-286 (schema)Tool schema definition including name, description, and input schema 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 notion_query_database tool (as queryDatabaseTool) in the MCP server's 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/types/args.ts:80-91 (schema)TypeScript interface for QueryDatabaseArgs used in tool handler for type casting.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"; }