Better Notion MCP

Instructions

Implementation Reference

• src/tools/composite/users.ts:19-118 (handler)

  Main execution handler for the 'users' tool. Supports actions: list (paginated users), get (by ID), me (bot/integration user), from_workspace (users from accessible pages metadata). Uses Notion API users.list/retrieve and fallback search.

  export async function users(notion: Client, input: UsersInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.action) {
        case 'list': {
          const usersList = await autoPaginate((cursor) =>
            notion.users.list({
              start_cursor: cursor,
              page_size: 100
            })
          )
  
          return {
            action: 'list',
            total: usersList.length,
            users: usersList.map((user: any) => ({
              id: user.id,
              type: user.type,
              name: user.name || 'Unknown',
              avatar_url: user.avatar_url,
              email: user.type === 'person' ? user.person?.email : undefined
            }))
          }
        }
  
        case 'get': {
          if (!input.user_id) {
            throw new NotionMCPError('user_id required for get action', 'VALIDATION_ERROR', 'Provide user_id')
          }
  
          const user = await notion.users.retrieve({ user_id: input.user_id })
  
          return {
            action: 'get',
            id: user.id,
            type: user.type,
            name: (user as any).name || 'Unknown',
            avatar_url: (user as any).avatar_url,
            email: user.type === 'person' ? (user as any).person?.email : undefined
          }
        }
  
        case 'me': {
          const botUser = await notion.users.retrieve({ user_id: 'me' })
  
          return {
            action: 'me',
            id: (botUser as any).id,
            type: (botUser as any).type,
            name: (botUser as any).name || 'Bot',
            bot: (botUser as any).bot
          }
        }
  
        case 'from_workspace': {
          // Alternative method: Search pages and extract user info from metadata
          // This bypasses the permission issue with direct users.list() call
          const searchResults: any = await notion.search({
            filter: { property: 'object', value: 'page' },
            page_size: 100
          })
  
          const usersMap = new Map<string, any>()
  
          for (const page of searchResults.results) {
            // Extract users from created_by and last_edited_by
            if (page.created_by) {
              usersMap.set(page.created_by.id, {
                id: page.created_by.id,
                type: page.created_by.object,
                source: 'page_metadata'
              })
            }
            if (page.last_edited_by) {
              usersMap.set(page.last_edited_by.id, {
                id: page.last_edited_by.id,
                type: page.last_edited_by.object,
                source: 'page_metadata'
              })
            }
          }
  
          const users = Array.from(usersMap.values())
  
          return {
            action: 'from_workspace',
            total: users.length,
            users,
            note: 'Users extracted from accessible pages. Use "me" action for bot info, or share more pages for more users.'
          }
        }
  
        default:
          throw new NotionMCPError(
            `Unknown action: ${input.action}`,
            'VALIDATION_ERROR',
            'Supported actions: list, get, me, from_workspace'
          )
      }
    })()
  }

• src/tools/composite/users.ts:10-13 (schema)

  TypeScript input interface for the users tool handler.

  export interface UsersInput {
    action: 'list' | 'get' | 'me' | 'from_workspace'
    user_id?: string
  }

• src/tools/registry.ts:143-158 (registration)

  MCP tool registration: defines name, description, and JSON schema for 'users' tool in the TOOLS array.

  {
    name: 'users',
    description: 'User info: list, get, me, from_workspace. Use from_workspace if list fails due to permissions.',
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['list', 'get', 'me', 'from_workspace'],
          description: 'Action to perform'
        },
        user_id: { type: 'string', description: 'User ID (for get action)' }
      },
      required: ['action']
    }
  },

• src/tools/registry.ts:305-307 (registration)

  Tool dispatcher in MCP callToolRequest handler: calls the users function based on tool name.

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

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

  Import of the users tool handler function.

  import { users } from './composite/users.js'