Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/list.handlers.ts:132-178 (handler)

  Core handler function that executes the addUserToList tool: verifies user and list existence, adds user via Twitter API v2, handles errors including rate limits and permissions.

  export async function handleAddUserToList(
      client: TwitterClient | null,
      args: AddUserToListArgs
  ): Promise<HandlerResponse> {
      if (!client) {
          return createMissingTwitterApiKeyResponse('addUserToList');
      }
      try {
          // First, verify the user exists and get their username for the response message
          const user = await client.getUserById(args.userId);
          if (!user.data) {
              throw new Error(`User with ID ${args.userId} not found`);
          }
  
          // Then verify the list exists and get its name for the response message
          const list = await client.getList(args.listId);
          if (!list.data) {
              throw new Error(`List with ID ${args.listId} not found`);
          }
  
          // Now try to add the user to the list
          await client.addListMember(args.listId, args.userId);
  
          return createResponse(
              `Successfully added user @${user.data.username} to list "${list.data.name}"`
          );
      } catch (error) {
          if (error instanceof ApiResponseError) {
              // Handle specific Twitter API errors
              if (error.rateLimitError && error.rateLimit) {
                  const resetMinutes = Math.ceil(error.rateLimit.reset / 60);
                  throw new Error(`Rate limit exceeded. Please try again in ${resetMinutes} minutes.`);
              }
              if (error.code === 403) {
                  throw new Error('You do not have permission to add members to this list.');
              }
              if (error.code === 404) {
                  throw new Error('The specified user or list could not be found.');
              }
              throw new Error(`Twitter API Error: ${error.message}`);
          }
          if (error instanceof Error) {
              throw new Error(formatTwitterError(error, 'adding user to list'));
          }
          throw new Error('Failed to add user to list: Unknown error occurred');
      }
  }

• src/tools.ts:333-343 (schema)

  Input schema definition for the addUserToList tool, specifying listId and username parameters.

  addUserToList: {
      description: 'Add a user to a Twitter list',
      inputSchema: {
          type: 'object',
          properties: {
              listId: { type: 'string', description: 'The ID of the list' },
              username: { type: 'string', description: 'The username of the user to add' }
          },
          required: ['listId', 'username'],
      },
  },

• src/index.ts:289-292 (registration)

  Tool dispatch/registration in MCP server's CallToolRequestHandler switch statement, mapping tool call to handlerAddUserToList.

  case 'addUserToList': {
      const { listId, userId } = request.params.arguments as { listId: string; userId: string };
      response = await handleAddUserToList(client, { listId, userId });
      break;

• src/index.ts:104-109 (registration)

  MCP tool listing registration: exposes all tools from TOOLS object (including addUserToList) via ListToolsRequestSchema.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: Object.entries(TOOLS).map(([name, tool]) => ({
          name,
          ...tool
      }))
  }));

• src/handlers/list.handlers.ts:19-22 (schema)

  TypeScript interface defining expected arguments for the handler (note: uses userId vs schema's username).

  export interface AddUserToListArgs {
      listId: string;
      userId: string;
  }