Twitter MCP Server

Instructions

Implementation Reference

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

  Core handler function that fetches and formats a user's owned Twitter lists and list memberships using the Twitter API v2.

  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/tools.ts:379-402 (schema)

  MCP tool schema definition including input validation schema for getUserLists tool.

  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 MCP server request handler switch statement.

  case 'getUserLists': {
      const { username, maxResults } = request.params.arguments as { username: string; maxResults?: number };
      response = await handleGetUserLists(client, { username, maxResults });
      break;

• src/index.ts:41-45 (registration)

  Import of the handleGetUserLists handler function into the main server index.

  handleCreateList,
  handleAddUserToList,
  handleRemoveUserFromList,
  handleGetListMembers,
  handleGetUserLists

• src/handlers/list.handlers.ts:98-108 (helper)

  Helper function to format 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`;