Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/tweet.handlers.ts:121-148 (handler)

  Core handler function that executes the getUserTimeline tool logic using Twitter API v2 to fetch recent tweets from a user's timeline.

  export const handleGetUserTimeline = async (
      client: TwitterClient | null,
      { userId, maxResults = 10, tweetFields = ['created_at', 'public_metrics', 'author_id'], expansions = ['author_id' as TTweetv2Expansion], userFields = ['username' as TTweetv2UserField] }: GetUserTimelineArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('Get User Timeline');
      }
  
      try {
          const timeline = await client.getUserTimeline(userId, {
              max_results: maxResults,
              'tweet.fields': tweetFields.join(','),
              expansions,
              'user.fields': userFields
          });
  
          if (!timeline.data || timeline.data.length === 0) {
              return createResponse(`No tweets found in timeline for user: ${userId}`);
          }
  
          return createResponse(`Timeline tweets: ${JSON.stringify(timeline.data, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              throw new Error(formatTwitterError(error, 'getting user timeline'));
          }
          throw new Error('Failed to get user timeline: Unknown error occurred');
      }
  };

• src/tools.ts:120-141 (schema)

  MCP tool schema definition including input validation (username required, optional maxResults and tweetFields) and description.

  getUserTimeline: {
      description: 'Get tweets from a specific user\'s timeline',
      inputSchema: {
          type: 'object',
          properties: {
              username: { 
                  type: 'string', 
                  description: 'The username of the user whose timeline to fetch' 
              },
              maxResults: { 
                  type: 'number', 
                  description: 'Maximum number of tweets to return (default: 10, max: 100)' 
              },
              tweetFields: { 
                  type: 'array', 
                  items: { type: 'string' },
                  description: 'Additional tweet fields to include' 
              }
          },
          required: ['username']
      }
  },

• src/index.ts:222-258 (registration)

  Registers the getUserTimeline tool in the MCP server dispatch switch: converts username to userId using getUserByUsername, then calls the handler.

              case 'getUserTimeline': {
                  const { username, maxResults, tweetFields } = request.params.arguments as { 
                      username: string; 
                      maxResults?: number; 
                      tweetFields?: string[] 
                  };
                  
                  if (!client) {
                      response = { response: `📋 **Get User Timeline requires Twitter API credentials**
  
  To use Twitter tools, please:
  
  1. **Create a Twitter Developer Account** at https://developer.twitter.com
  2. **Create a new Twitter App** and generate API keys
  3. **Add to your .env file:**
     \`\`\`
     X_API_KEY=your_api_key_here
     X_API_SECRET=your_api_secret_here
     X_ACCESS_TOKEN=your_access_token_here
     X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
     \`\`\`
  4. **Restart the MCP server**
  
  **Alternative:** Use the enhanced SocialData.tools research tools instead (if available)`, tools: [] };
                      break;
                  }
                  
                  // Convert username to userId
                  const userResponse = await client.getUserByUsername(username);
                  const userId = userResponse.data.id;
                  
                  response = await handleGetUserTimeline(client, { 
                      userId, 
                      maxResults, 
                      tweetFields 
                  });
                  break;

• src/types/handlers.ts:32-38 (schema)

  TypeScript interface defining arguments for the handler function (userId required, optional fields matching Twitter API v2 parameters).

  export interface GetUserTimelineArgs {
      userId: string;
      maxResults?: number;
      tweetFields?: string[];
      expansions?: TTweetv2Expansion[];
      userFields?: TTweetv2UserField[];
  }