Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/user.handlers.ts:152-190 (handler)

  Core handler function that executes the tool logic: fetches the user by username, then retrieves the list of users they are following using Twitter API v2 'following' endpoint, handles errors including permissions.

  export const handleGetFollowing: TwitterHandler<GetFollowingArgs> = async (
      client: TwitterClient | null,
      { username, maxResults, userFields }: GetFollowingArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getFollowing');
      }
  
      try {
          const user = await client.v2.userByUsername(username);
          if (!user.data) {
              throw new Error(`User not found: ${username}`);
          }
  
          const following = await client.v2.following(user.data.id, {
              max_results: maxResults,
              'user.fields': userFields?.join(',') || 'description,profile_image_url,public_metrics,verified'
          });
  
          if (!following.data || !Array.isArray(following.data) || following.data.length === 0) {
              return createResponse(`User ${username} is not following anyone`);
          }
  
          const responseData = {
              following: following.data,
              meta: following.meta
          };
  
          return createResponse(`Users followed by ${username}: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              if (error.message.includes('403')) {
                  throw new Error(`Get following 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 following 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 following'));
          }
          throw error;
      }
  };

• src/tools.ts:297-320 (schema)

  MCP tool schema definition: specifies description and inputSchema for getFollowing tool with parameters username (required), maxResults, userFields.

  getFollowing: {
      description: 'Get a list of users that a user is following',
      inputSchema: {
          type: 'object',
          properties: {
              username: { type: 'string', description: 'The username of the user whose following list to fetch' },
              maxResults: { 
                  type: 'number', 
                  description: 'The maximum number of results to return (default: 100, max: 1000)',
                  minimum: 1,
                  maximum: 1000
              },
              userFields: { 
                  type: 'array', 
                  items: { 
                      type: 'string',
                      enum: ['description', 'profile_image_url', 'public_metrics', 'verified', 'location', 'url']
                  },
                  description: 'Additional user fields to include in the response'
              },
          },
          required: ['username'],
      },
  },

• src/index.ts:275-278 (registration)

  Tool call dispatch/registration in the MCP CallToolRequestHandler switch statement: extracts arguments and invokes the handleGetFollowing function.

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

• src/types.ts:83-87 (schema)

  TypeScript interface defining input arguments for the getFollowing handler.

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

• src/types.ts:377-400 (helper)

  Runtime type assertion helper function to validate getFollowing arguments.

  export function assertGetFollowingArgs(args: unknown): asserts args is GetFollowingArgs {
      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');
              }
          }
      }
  }