Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/list.handlers.ts:36-96 (handler)

  Main handler function that executes the getUserLists tool: fetches user's owned lists and list memberships via Twitter API v2, formats response with list details.
  export async function handleGetUserLists( client: TwitterClient | null, args: GetUserListsArgs ): Promise<HandlerResponse> { if (!client) { return createMissingTwitterApiKeyResponse('getUserLists'); } try { const user = await client.getUserByUsername(args.username); if (!user.data) { throw new Error('User not found'); } const options = { 'list.fields': ['created_at', 'follower_count', 'member_count', 'private', 'description'], expansions: ['owner_id'], 'user.fields': ['username', 'name', 'verified'], max_results: args.maxResults, pageLimit: args.pageLimit }; const [ownedLists, memberLists] = await Promise.all([ client.getOwnedLists(user.data.id, options), client.getListMemberships(user.data.id, options) ]); const ownedListsCount = ownedLists.meta.result_count || 0; const memberListsCount = memberLists.meta.result_count || 0; let responseText = `Found ${ownedListsCount} owned lists and ${memberListsCount} list memberships.\n\n`; if (ownedLists.data && ownedLists.data.length > 0) { responseText += 'Owned Lists:\n'; ownedLists.data.forEach((list) => { responseText += formatListInfo(list); }); responseText += '\n'; } if (memberLists.data && memberLists.data.length > 0) { responseText += 'Member of Lists:\n'; memberLists.data.forEach((list) => { responseText += formatListInfo(list); }); } const totalRetrieved = (ownedLists.meta.total_retrieved || 0) + (memberLists.meta.total_retrieved || 0); const totalRequested = args.maxResults ? args.maxResults * 2 : undefined; if (totalRequested && totalRetrieved >= totalRequested) { responseText += '\nNote: Maximum requested results reached. There might be more lists available.'; } return createResponse(responseText); } catch (error) { if (error instanceof Error) { throw new Error(formatTwitterError(error, 'getting user lists')); } throw new Error('Failed to get user lists: Unknown error occurred'); } }
• src/handlers/list.handlers.ts:98-108 (helper)

  Helper function to format individual list information for the response text.
  function formatListInfo(list: ListV2): string { const name = list.name.length > 50 ? `${list.name.substring(0, 47)}...` : list.name; const description = list.description ? list.description.length > 100 ? `${list.description.substring(0, 97)}...` : list.description : ''; return `- ${name} (${list.member_count} members${list.private ? ', private' : ''})${ description ? `: ${description}` : '' }\n`;
• src/tools.ts:379-402 (schema)

  MCP tool schema definition for getUserLists, including input schema with username (required), maxResults, and listFields.
  getUserLists: { description: 'Get lists owned by a user', inputSchema: { type: 'object', properties: { username: { type: 'string', description: 'The username of the user whose lists to fetch' }, maxResults: { type: 'number', description: 'The maximum number of results to return (default: 100, max: 100)', minimum: 1, maximum: 100 }, listFields: { type: 'array', items: { type: 'string', enum: ['created_at', 'follower_count', 'member_count', 'private', 'description'] }, description: 'Additional list fields to include in the response' }, }, required: ['username'], }, },
• src/index.ts:308-311 (registration)

  Tool dispatch/registration in the main CallToolRequestHandler switch statement, calling the handleGetUserLists function.
  case 'getUserLists': { const { username, maxResults } = request.params.arguments as { username: string; maxResults?: number }; response = await handleGetUserLists(client, { username, maxResults }); break;
• src/types.ts:111-115 (schema)

  TypeScript interface defining input arguments for the getUserLists handler.
  export interface GetUserListsArgs { username: string; maxResults?: number; listFields?: string[]; }