query-database
Retrieve and filter Notion database entries using specific criteria, sorting options, and pagination controls to access structured workspace data.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The ID of the database to query | |
| filter | No | JSON string of filter criteria | |
| sorts | No | JSON string of sort criteria | |
| page_size | No | Number of results to return (max 100) | |
| start_cursor | No | Pagination cursor |
Implementation Reference
- src/lib/mcp-server.ts:135-183 (handler)The main handler function for the 'query-database' MCP tool. Parses JSON strings for filter and sorts, calls NotionService.queryDatabase, formats results as JSON text content or error response.async ({ database_id, filter, sorts, page_size, start_cursor }) => { const params: any = { database_id, page_size, start_cursor }; // Parse filter and sorts from JSON strings to objects // Example filter: "{\"property\":\"Status\",\"select\":{\"equals\":\"Done\"}}" // Example sorts: "[{\"property\":\"Priority\",\"direction\":\"descending\"}]" try { if (filter) params.filter = JSON.parse(filter); if (sorts) params.sorts = JSON.parse(sorts); } catch (parseError) { console.error("Error parsing JSON parameters:", parseError); return { content: [ { type: "text", text: `Error: Failed to parse JSON parameters - ${ (parseError as Error).message }. Make sure filter and sorts are valid JSON strings.`, }, ], isError: true, }; } try { const results = await this.notionService.queryDatabase(params); return { content: [ { type: "text", text: JSON.stringify(results, null, 2), }, ], }; } catch (error) { console.error("Error in query-database tool:", error); return { content: [ { type: "text", text: `Error: Failed to query database - ${ (error as Error).message }`, }, ], isError: true, }; } }
- src/lib/mcp-server.ts:120-134 (schema)Zod input schema for the 'query-database' tool defining parameters like database_id, filter (JSON), sorts (JSON), page_size, and start_cursor.{ database_id: z.string().describe("The ID of the database to query"), filter: z .string() .optional() .describe("JSON string of filter criteria"), sorts: z.string().optional().describe("JSON string of sort criteria"), page_size: z .number() .min(1) .max(100) .optional() .describe("Number of results to return (max 100)"), start_cursor: z.string().optional().describe("Pagination cursor"), },
- src/lib/mcp-server.ts:118-184 (registration)Registration of the 'query-database' tool on the McpServer instance within registerDatabaseTools().this.server.tool( "query-database", { database_id: z.string().describe("The ID of the database to query"), filter: z .string() .optional() .describe("JSON string of filter criteria"), sorts: z.string().optional().describe("JSON string of sort criteria"), page_size: z .number() .min(1) .max(100) .optional() .describe("Number of results to return (max 100)"), start_cursor: z.string().optional().describe("Pagination cursor"), }, async ({ database_id, filter, sorts, page_size, start_cursor }) => { const params: any = { database_id, page_size, start_cursor }; // Parse filter and sorts from JSON strings to objects // Example filter: "{\"property\":\"Status\",\"select\":{\"equals\":\"Done\"}}" // Example sorts: "[{\"property\":\"Priority\",\"direction\":\"descending\"}]" try { if (filter) params.filter = JSON.parse(filter); if (sorts) params.sorts = JSON.parse(sorts); } catch (parseError) { console.error("Error parsing JSON parameters:", parseError); return { content: [ { type: "text", text: `Error: Failed to parse JSON parameters - ${ (parseError as Error).message }. Make sure filter and sorts are valid JSON strings.`, }, ], isError: true, }; } try { const results = await this.notionService.queryDatabase(params); return { content: [ { type: "text", text: JSON.stringify(results, null, 2), }, ], }; } catch (error) { console.error("Error in query-database tool:", error); return { content: [ { type: "text", text: `Error: Failed to query database - ${ (error as Error).message }`, }, ], isError: true, }; } } );
- src/lib/mcp-server.ts:850-865 (helper)Utility function to stringify filter objects into JSON for use as the 'filter' parameter in query-database tool.* Helper function to create a properly formatted filter string for the query-database tool * @param filter The filter object * @returns A JSON string representation of the filter * * @example * const filter = createFilterString({ * property: "Status", * select: { * equals: "Done" * } * }); * // Returns: "{\"property\":\"Status\",\"select\":{\"equals\":\"Done\"}}" */ export function createFilterString(filter: any): string { return JSON.stringify(filter); }
- src/lib/notion.ts:84-105 (helper)NotionService.queryDatabase method invoked by the tool handler, which constructs params and calls the Notion SDK's databases.query API.async queryDatabase(params: DatabaseQuery) { try { const queryParams: Parameters<typeof this.client.databases.query>[0] = { database_id: params.database_id, page_size: params.page_size, start_cursor: params.start_cursor, }; // Only add filter and sorts if they exist to avoid type issues if (params.filter) { queryParams.filter = params.filter as any; } if (params.sorts) { queryParams.sorts = params.sorts as any; } return await this.client.databases.query(queryParams); } catch (error) { this.handleError(error); } }