notion_query_database
Retrieve and filter data from Notion databases using queries, sorting, and pagination to extract specific information for analysis or integration.
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/server/index.ts:178-192 (handler)Main handler for notion_query_database tool in the switch statement. Validates required arguments (database_id) and calls the NotionClientWrapper.queryDatabase method with filter, sorts, start_cursor, and page_size parameters.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/client/index.ts:209-236 (handler)Actual implementation of queryDatabase in NotionClientWrapper class. Constructs the request body with optional filter, sorts, start_cursor, and page_size, then makes a POST request to Notion's /databases/{id}/query endpoint.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:279-321 (schema)Tool schema definition for notion_query_database. Defines the tool name, description, and inputSchema with properties for database_id (required), filter, sorts, start_cursor, page_size, and format parameters.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/types/args.ts:87-98 (schema)TypeScript interface defining the QueryDatabaseArgs type with types for all parameters: database_id, filter, sorts, start_cursor, page_size, and optional format field.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"; }
- src/server/index.ts:331-331 (registration)Tool registration in the ListToolsRequestSchema handler where schemas.queryDatabaseTool is added to the allTools array, making it available to MCP clients.schemas.queryDatabaseTool,