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