MCP Notion Server (@suncreation)

Instructions

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,