query_pages
Retrieve Notion database pages matching specific conditions using filters and sorting. Find tasks by status, projects by due date, or records by custom criteria.
Instructions
Queries and retrieves pages (records) from a Notion database. Supports filtering and sorting. Examples: "tasks with status In Progress", "projects due this week", "tasks assigned to me". Retrieve pages matching specific conditions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| databaseId | Yes | The ID of the Notion database to query (32 or 36 character UUID format). Example: "123e4567-e89b-12d3-a456-426614174000" | |
| filter | No | Filter conditions (optional). Follows Notion API filter syntax. Examples: - Status equals "In Progress": { "property": "Status", "select": { "equals": "In Progress" } } - Checkbox is checked: { "property": "Completed", "checkbox": { "equals": true } } - Date is this week: { "property": "Due Date", "date": { "this_week": {} } } - Multiple conditions (AND): { "and": [condition1, condition2] } - Multiple conditions (OR): { "or": [condition1, condition2] } | |
| sorts | No | Sort conditions (optional). Array of sort specifications. Examples: - Date ascending: [{ "property": "Due Date", "direction": "ascending" }] - Priority descending: [{ "property": "Priority", "direction": "descending" }] - Created time descending: [{ "timestamp": "created_time", "direction": "descending" }] | |
| startCursor | No | Pagination cursor (optional). Use the nextCursor from a previous query to fetch the next page of results. | |
| pageSize | No | Number of pages to retrieve at once (optional, default: 100, max: 100). Use with pagination for large datasets. |
Implementation Reference
- MCP tool handler method that executes the query_pages tool. It calls the QueryPagesUseCase with input arguments and formats the response as MCP content.private async handleQueryPages(args: any) { const result = await this.dependencies.queryPagesUseCase.execute({ databaseId: args.databaseId, filter: args.filter, sorts: args.sorts, startCursor: args.startCursor, pageSize: args.pageSize, }); return { content: [ { type: 'text' as const, text: JSON.stringify( { pages: result.pages.map((page) => ({ id: page.id.toString(), properties: page.properties, createdTime: page.createdTime, archived: page.archived, })), hasMore: result.hasMore, nextCursor: result.nextCursor, }, null, 2 ), }, ], }; }
- src/presentation/mcp/MCPServer.ts:217-258 (registration)Tool registration in the getTools() method, defining the name 'query_pages', description, and input schema for the MCP ListTools response.{ name: 'query_pages', description: 'Queries and retrieves pages (records) from a Notion database. Supports filtering and sorting. Examples: "tasks with status In Progress", "projects due this week", "tasks assigned to me". Retrieve pages matching specific conditions.', inputSchema: { type: 'object', properties: { databaseId: { type: 'string', description: 'The ID of the Notion database to query (32 or 36 character UUID format). Example: "123e4567-e89b-12d3-a456-426614174000"', }, filter: { type: 'object', description: `Filter conditions (optional). Follows Notion API filter syntax. Examples: - Status equals "In Progress": { "property": "Status", "select": { "equals": "In Progress" } } - Checkbox is checked: { "property": "Completed", "checkbox": { "equals": true } } - Date is this week: { "property": "Due Date", "date": { "this_week": {} } } - Multiple conditions (AND): { "and": [condition1, condition2] } - Multiple conditions (OR): { "or": [condition1, condition2] }`, }, sorts: { type: 'array', description: `Sort conditions (optional). Array of sort specifications. Examples: - Date ascending: [{ "property": "Due Date", "direction": "ascending" }] - Priority descending: [{ "property": "Priority", "direction": "descending" }] - Created time descending: [{ "timestamp": "created_time", "direction": "descending" }]`, }, startCursor: { type: 'string', description: 'Pagination cursor (optional). Use the nextCursor from a previous query to fetch the next page of results.', }, pageSize: { type: 'number', description: 'Number of pages to retrieve at once (optional, default: 100, max: 100). Use with pagination for large datasets.', }, }, required: ['databaseId'], }, },
- TypeScript interface defining the input schema for the QueryPagesUseCase, matching the MCP tool input.export interface QueryPagesInput { databaseId: string; filter?: Record<string, unknown>; sorts?: Array<{ property: string; direction: 'ascending' | 'descending' }>; startCursor?: string; pageSize?: number; }
- Core business logic handler in QueryPagesUseCase.execute(), which validates input, constructs query options, and delegates to the page repository.export class QueryPagesUseCase { constructor(private readonly pageRepository: IPageRepository) {} async execute(input: QueryPagesInput): Promise<PageQueryResult> { const databaseId = new DatabaseId(input.databaseId); const options: PageQueryOptions = { filter: input.filter, sorts: input.sorts, startCursor: input.startCursor, pageSize: input.pageSize, }; return await this.pageRepository.query(databaseId, options); } }