getUserTimeline
Fetch tweets from a specific user's timeline by providing their username, with options to limit results and include additional tweet fields.
Instructions
Get tweets from a specific user's timeline
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of tweets to return (default: 10, max: 100) | |
| tweetFields | No | Additional tweet fields to include | |
| username | Yes | The username of the user whose timeline to fetch |
Implementation Reference
- src/handlers/tweet.handlers.ts:121-148 (handler)The core handler function that executes the getUserTimeline tool logic, fetching the user's recent tweets using the Twitter API v2 user timeline endpoint.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/index.ts:222-258 (registration)The dispatch logic in the main MCP server request handler that processes getUserTimeline tool calls, converts username to userId, and invokes the handler function.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/tools.ts:120-141 (schema)The tool registration and input schema definition for getUserTimeline, exported as part of the TOOLS object used by the MCP server to list available tools.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/types/handlers.ts:32-38 (schema)TypeScript interface defining the arguments expected by the handleGetUserTimeline handler function.export interface GetUserTimelineArgs { userId: string; maxResults?: number; tweetFields?: string[]; expansions?: TTweetv2Expansion[]; userFields?: TTweetv2UserField[]; }