Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/moderation.handlers.ts:104-154 (handler)

  Main handler function that implements the getBlockedUsers tool logic, fetching the authenticated user's blocked users list from Twitter API v2 using client.v2.userBlockingUsers()

  export const handleGetBlockedUsers: TwitterHandler<GetBlockedUsersArgs> = async (
      client: TwitterClient | null,
      { maxResults = 100, paginationToken, userFields }: GetBlockedUsersArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getBlockedUsers');
      }
      
      try {
          // Get authenticated user's ID
          const me = await client.v2.me();
          const myUserId = me.data.id;
  
          const options: any = {
              max_results: Math.min(maxResults, 1000) // API max is 1000
          };
  
          if (paginationToken) {
              options.pagination_token = paginationToken;
          }
  
          if (userFields && userFields.length > 0) {
              options['user.fields'] = userFields.join(',');
          } else {
              // Default user fields for better response
              options['user.fields'] = 'id,name,username,public_metrics,description,verified';
          }
  
          const blockedUsers = await client.v2.userBlockingUsers(myUserId, options);
  
          // The paginator returns data nested: { data: [users], meta: {...} }
          const userData = blockedUsers.data?.data;
          const metaData = blockedUsers.data?.meta || blockedUsers.meta;
  
          if (!userData || !Array.isArray(userData) || userData.length === 0) {
              return createResponse('No blocked users found.');
          }
  
          const responseData = {
              blockedUsers: userData,
              meta: metaData
          };
  
          return createResponse(`Retrieved ${userData.length} blocked users: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              throw new Error(formatTwitterError(error, 'getting blocked users'));
          }
          throw error;
      }
  };

• src/types/handlers.ts:125-129 (schema)

  TypeScript interface defining the input arguments for the getBlockedUsers handler

  export interface GetBlockedUsersArgs {
      maxResults?: number;
      paginationToken?: string;
      userFields?: string[];
  }

• src/tools.ts:647-673 (registration)

  MCP tool registration defining the getBlockedUsers tool with description and input schema

  getBlockedUsers: {
      description: 'Retrieve a paginated list of users you have blocked',
      inputSchema: {
          type: 'object',
          properties: {
              maxResults: { 
                  type: 'number', 
                  description: 'Maximum number of blocked users to return (default: 100, max: 1000)',
                  minimum: 1,
                  maximum: 1000
              },
              paginationToken: { 
                  type: 'string', 
                  description: 'Pagination token for retrieving next page of results' 
              },
              userFields: { 
                  type: 'array', 
                  items: { 
                      type: 'string',
                      enum: ['id', 'name', 'username', 'description', 'profile_image_url', 'public_metrics', 'verified', 'location', 'url']
                  },
                  description: 'User fields to include in the response' 
              }
          },
          required: []
      }
  },

• src/index.ts:397-404 (registration)

  Server request handler dispatch case that routes 'getBlockedUsers' tool calls to the handleGetBlockedUsers function

  case 'getBlockedUsers': {
      const { maxResults, paginationToken, userFields } = request.params.arguments as { 
          maxResults?: number; 
          paginationToken?: string; 
          userFields?: string[] 
      };
      response = await handleGetBlockedUsers(client, { maxResults, paginationToken, userFields });
      break;