Notion MCP Server

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