Better Notion MCP

Instructions

Implementation Reference

• src/tools/composite/databases.ts:58-96 (handler)

  Primary exported handler function for the 'databases' tool. Dispatches to sub-handlers based on the 'action' input parameter.

  export async function databases(notion: Client, input: DatabasesInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.action) {
        case 'create':
          return await createDatabase(notion, input)
  
        case 'get':
          return await getDatabase(notion, input)
  
        case 'query':
          return await queryDatabase(notion, input)
  
        case 'create_page':
          return await createDatabasePages(notion, input)
  
        case 'update_page':
          return await updateDatabasePages(notion, input)
  
        case 'delete_page':
          return await deleteDatabasePages(notion, input)
  
        case 'create_data_source':
          return await createDataSource(notion, input)
  
        case 'update_data_source':
          return await updateDataSource(notion, input)
  
        case 'update_database':
          return await updateDatabaseContainer(notion, input)
  
        default:
          throw new NotionMCPError(
            `Unknown action: ${input.action}`,
            'VALIDATION_ERROR',
            'Supported actions: create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database'
          )
      }
    })()
  }

• src/tools/composite/databases.ts:12-53 (schema)

  TypeScript interface defining the input shape for the databases tool, including all supported actions and parameters.

  export interface DatabasesInput {
    action:
      | 'create'
      | 'get'
      | 'query'
      | 'create_page'
      | 'update_page'
      | 'delete_page'
      | 'create_data_source'
      | 'update_data_source'
      | 'update_database'
  
    // Common params
    database_id?: string
    data_source_id?: string
  
    // Create database params
    parent_id?: string
    title?: string
    description?: string
    properties?: Record<string, any>
    is_inline?: boolean
    icon?: string
    cover?: string
  
    // Query params
    filters?: any
    sorts?: any[]
    limit?: number
    search?: string
  
    // Page operations params (create/update/delete database items)
    page_id?: string
    page_ids?: string[]
    page_properties?: Record<string, any>
  
    // Bulk operations
    pages?: Array<{
      page_id?: string
      properties: Record<string, any>
    }>
  }

• src/tools/registry.ts:83-123 (registration)

  MCP tool registration in the TOOLS array, including name, description, and JSON inputSchema for validation.

  name: 'databases',
  description:
    'Database operations: create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database. Databases contain data sources with schema and rows.',
  inputSchema: {
    type: 'object',
    properties: {
      action: {
        type: 'string',
        enum: [
          'create',
          'get',
          'query',
          'create_page',
          'update_page',
          'delete_page',
          'create_data_source',
          'update_data_source',
          'update_database'
        ],
        description: 'Action to perform'
      },
      database_id: { type: 'string', description: 'Database ID (container)' },
      data_source_id: { type: 'string', description: 'Data source ID (for update_data_source action)' },
      parent_id: { type: 'string', description: 'Parent page ID (for create/update_database)' },
      title: { type: 'string', description: 'Title (for database or data source)' },
      description: { type: 'string', description: 'Description' },
      properties: { type: 'object', description: 'Schema properties (for create/update data source)' },
      is_inline: { type: 'boolean', description: 'Display as inline (for create/update_database)' },
      icon: { type: 'string', description: 'Emoji icon (for update_database)' },
      cover: { type: 'string', description: 'Cover image URL (for update_database)' },
      filters: { type: 'object', description: 'Query filters (for query action)' },
      sorts: { type: 'array', items: { type: 'object' }, description: 'Query sorts' },
      limit: { type: 'number', description: 'Max query results' },
      search: { type: 'string', description: 'Smart search across text fields (for query)' },
      page_id: { type: 'string', description: 'Single page ID (for update_page)' },
      page_ids: { type: 'array', items: { type: 'string' }, description: 'Multiple page IDs (for delete_page)' },
      page_properties: { type: 'object', description: 'Page properties to update (for update_page)' },
      pages: { type: 'array', items: { type: 'object' }, description: 'Array of pages for bulk create/update' }
    },
    required: ['action']
  }

• src/tools/registry.ts:299-301 (registration)

  Dispatch in the CallToolRequestSchema handler that invokes the databases tool function.

  case 'databases':
    result = await databases(notion, args as any)
    break

• src/tools/composite/databases.ts:205-303 (helper)

  Example helper function for 'query' action, demonstrating database querying with filters, sorting, and pagination.

  async function queryDatabase(notion: Client, input: DatabasesInput): Promise<any> {
    if (!input.database_id) {
      throw new NotionMCPError('database_id required for query action', 'VALIDATION_ERROR', 'Provide database_id')
    }
  
    // First, get data source ID from database
    const database: any = await notion.databases.retrieve({
      database_id: input.database_id
    })
  
    if (!database.data_sources || database.data_sources.length === 0) {
      throw new NotionMCPError('No data sources found in database', 'VALIDATION_ERROR', 'Database has no data sources')
    }
  
    const dataSourceId = database.data_sources[0].id
  
    let filter = input.filters
  
    // Smart search across text properties
    if (input.search && !filter) {
      const dataSource: any = await (notion as any).dataSources.retrieve({
        data_source_id: dataSourceId
      })
  
      const textProps = Object.entries(dataSource.properties || {})
        .filter(([_, prop]: [string, any]) => ['title', 'rich_text'].includes(prop.type))
        .map(([name]) => name)
  
      if (textProps.length > 0) {
        filter = {
          or: textProps.map((propName) => ({
            property: propName,
            rich_text: { contains: input.search }
          }))
        }
      }
    }
  
    const queryParams: any = { data_source_id: dataSourceId }
    if (filter) queryParams.filter = filter
    if (input.sorts) queryParams.sorts = input.sorts
  
    // Fetch with pagination
    const allResults = await autoPaginate(async (cursor) => {
      const response: any = await (notion as any).dataSources.query({
        ...queryParams,
        start_cursor: cursor,
        page_size: 100
      })
      return {
        results: response.results,
        next_cursor: response.next_cursor,
        has_more: response.has_more
      }
    })
  
    // Limit results if specified
    const results = input.limit ? allResults.slice(0, input.limit) : allResults
  
    // Format results
    const formattedResults = results.map((page: any) => {
      const props: any = { page_id: page.id, url: page.url }
  
      for (const [key, prop] of Object.entries(page.properties)) {
        const p = prop as any
        if (p.type === 'title' && p.title) {
          props[key] = p.title.map((t: any) => t.plain_text).join('')
        } else if (p.type === 'rich_text' && p.rich_text) {
          props[key] = p.rich_text.map((t: any) => t.plain_text).join('')
        } else if (p.type === 'select' && p.select) {
          props[key] = p.select.name
        } else if (p.type === 'multi_select' && p.multi_select) {
          props[key] = p.multi_select.map((s: any) => s.name)
        } else if (p.type === 'number') {
          props[key] = p.number
        } else if (p.type === 'checkbox') {
          props[key] = p.checkbox
        } else if (p.type === 'url') {
          props[key] = p.url
        } else if (p.type === 'email') {
          props[key] = p.email
        } else if (p.type === 'phone_number') {
          props[key] = p.phone_number
        } else if (p.type === 'date' && p.date) {
          props[key] = p.date.start + (p.date.end ? ` to ${p.date.end}` : '')
        }
      }
  
      return props
    })
  
    return {
      action: 'query',
      database_id: input.database_id,
      data_source_id: dataSourceId,
      total: formattedResults.length,
      results: formattedResults
    }
  }