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'