Notion MCP Server

Instructions

Implementation Reference

• src/client/index.ts:173-200 (handler)

  Core implementation of the notion_query_database tool: makes POST request to Notion API /databases/{database_id}/query with optional filter, sorts, pagination.

  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/server/index.ts:163-176 (handler)

  MCP server handler for notion_query_database: validates database_id and delegates to NotionClientWrapper.queryDatabase.

  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/types/schemas.ts:244-286 (schema)

  Tool schema definition including name, description, and input schema for notion_query_database.

  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/server/index.ts:302-326 (registration)

  Registration of notion_query_database tool (as queryDatabaseTool) in the MCP server's listTools handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    const allTools = [
      schemas.appendBlockChildrenTool,
      schemas.retrieveBlockTool,
      schemas.retrieveBlockChildrenTool,
      schemas.deleteBlockTool,
      schemas.updateBlockTool,
      schemas.retrievePageTool,
      schemas.updatePagePropertiesTool,
      schemas.listAllUsersTool,
      schemas.retrieveUserTool,
      schemas.retrieveBotUserTool,
      schemas.createDatabaseTool,
      schemas.queryDatabaseTool,
      schemas.retrieveDatabaseTool,
      schemas.updateDatabaseTool,
      schemas.createDatabaseItemTool,
      schemas.createCommentTool,
      schemas.retrieveCommentsTool,
      schemas.searchTool,
    ];
    return {
      tools: filterTools(allTools, enabledToolsSet),
    };
  });

• src/types/args.ts:80-91 (schema)

  TypeScript interface for QueryDatabaseArgs used in tool handler for type casting.

  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";
  }