getUserTimeline

Fetch tweets from a specific user's timeline by providing their username, with options to control result count and include additional tweet fields.

Instructions

Get tweets from a specific user's timeline

Input Schema

TableJSON Schema

Name	Required	Description
`username`	Yes	The username of the user whose timeline to fetch
`maxResults`	No	Maximum number of tweets to return (default: 10, max: 100)
`tweetFields`	No	Additional tweet fields to include

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[];
}

Twitter MCP Server