query_pages
Retrieve Notion database pages with specific filters and sorting. Find tasks by status, projects by due date, or records matching custom conditions using Notion API syntax.
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
- src/presentation/mcp/MCPServer.ts:217-258 (registration)Registration of the 'query_pages' MCP tool, defining its name, description, and detailed input schema for database queries with optional filters, sorts, and pagination.{ 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'], }, },
- MCP server handler for the 'query_pages' tool. Extracts arguments, calls QueryPagesUseCase.execute(), and formats the response as JSON text 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 ), }, ], };
- TypeScript interface defining the input parameters for the QueryPagesUseCase, matching the tool's inputSchema.export interface QueryPagesInput { databaseId: string; filter?: Record<string, unknown>; sorts?: Array<{ property: string; direction: 'ascending' | 'descending' }>; startCursor?: string; pageSize?: number; }
- Core business logic for querying pages. Converts input to domain objects and delegates to the page repository for actual querying.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); } }