Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/user.handlers.ts:112-150 (handler)

  Core implementation of the getFollowers tool handler. Fetches the user by username, then retrieves their followers using Twitter API v2.followers endpoint, handles errors including permission requirements.

  export const handleGetFollowers: TwitterHandler<GetFollowersArgs> = async (
      client: TwitterClient | null,
      { username, maxResults, userFields }: GetFollowersArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getFollowers');
      }
  
      try {
          const user = await client.v2.userByUsername(username);
          if (!user.data) {
              throw new Error(`User not found: ${username}`);
          }
  
          const followers = await client.v2.followers(user.data.id, {
              max_results: maxResults,
              'user.fields': userFields?.join(',') || 'description,public_metrics'
          });
  
          if (!followers.data || !Array.isArray(followers.data) || followers.data.length === 0) {
              return createResponse(`No followers found for user: ${username}`);
          }
  
          const responseData = {
              followers: followers.data,
              meta: followers.meta
          };
  
          return createResponse(`Followers for ${username}: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              if (error.message.includes('403')) {
                  throw new Error(`Get followers functionality requires elevated permissions. This endpoint may require Pro tier access ($5,000/month) or special permission approval from X. Current Basic tier ($200/month) has limited access to follower data for privacy reasons. Contact X Developer Support or consider upgrading at https://developer.x.com/en/portal/products/pro`);
              }
              throw new Error(formatTwitterError(error, 'getting followers'));
          }
          throw error;
      }
  };

• src/tools.ts:273-296 (schema)

  MCP tool registration and input schema definition for getFollowers, including parameters for username, maxResults, and userFields.

  getFollowers: {
      description: 'Get followers of a user',
      inputSchema: {
          type: 'object',
          properties: {
              username: {
                  type: 'string',
                  description: 'The username of the account'
              },
              maxResults: {
                  type: 'number',
                  description: 'Maximum number of followers to return'
              },
              userFields: {
                  type: 'array',
                  items: {
                      type: 'string'
                  },
                  description: 'Fields to include in the user objects'
              }
          },
          required: ['username']
      }
  },

• src/index.ts:270-273 (registration)

  MCP server tool dispatch logic that routes 'getFollowers' calls to the handleGetFollowers function.

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

• src/types.ts:77-81 (schema)

  TypeScript interface defining the input arguments for getFollowers.

  export interface GetFollowersArgs {
      username: string;
      maxResults?: number;
      userFields?: string[];
  }

• src/types.ts:352-375 (schema)

  Runtime assertion function for validating getFollowers input arguments.

  export function assertGetFollowersArgs(args: unknown): asserts args is GetFollowersArgs {
      if (typeof args !== 'object' || args === null) {
          throw new Error('Invalid arguments: expected object');
      }
      if (!('username' in args) || typeof (args as any).username !== 'string') {
          throw new Error('Invalid arguments: expected username string');
      }
      if ('maxResults' in args) {
          const maxResults = (args as any).maxResults;
          if (typeof maxResults !== 'number' || maxResults < 1 || maxResults > 1000) {
              throw new Error('Invalid arguments: maxResults must be a number between 1 and 1000');
          }
      }
      if ('userFields' in args) {
          if (!Array.isArray((args as any).userFields)) {
              throw new Error('Invalid arguments: expected userFields to be an array');
          }
          for (const field of (args as any).userFields) {
              if (typeof field !== 'string') {
                  throw new Error('Invalid arguments: expected userFields to be an array of strings');
              }
          }
      }
  }