searchTweets
Search for tweets using specific queries to find relevant content and analyze Twitter data through customizable filters and result parameters.
Instructions
Search for tweets using a query string
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query | |
| maxResults | No | Maximum number of results to return | |
| tweetFields | No | Fields to include in the tweet objects |
Implementation Reference
- src/handlers/search.handlers.ts:23-58 (handler)The core handler function that executes the searchTweets tool logic. It performs a Twitter v2 search using the provided query, handles expansions for authors, formats the results, and includes tier requirement checks.export const handleSearchTweets: TwitterHandler<SearchTweetsArgs> = async ( client: TwitterClient | null, { query, maxResults = 10, tweetFields }: SearchTweetsArgs ): Promise<HandlerResponse> => { if (!client) { return createMissingTwitterApiKeyResponse('searchTweets'); } try { const searchResult = await client.v2.search(query, { max_results: maxResults, 'tweet.fields': tweetFields?.join(',') || 'created_at,public_metrics', expansions: ['author_id'], 'user.fields': ['username'] }); const tweets = Array.isArray(searchResult.data) ? searchResult.data : []; if (tweets.length === 0) { return createResponse(`No tweets found for query: ${query}`); } const formattedTweets = tweets.map((tweet: TweetV2): TweetWithAuthor => ({ ...tweet, author: searchResult.includes?.users?.find((u: UserV2) => u.id === tweet.author_id) })); return createResponse(`Search results: ${JSON.stringify(formattedTweets, null, 2)}`); } catch (error) { if (error instanceof Error) { if (error.message.includes('400') && error.message.includes('Invalid Request')) { throw new Error(`Search functionality requires Pro tier access ($5,000/month) or higher. Current Basic tier ($200/month) does not include recent search API access. Consider upgrading at https://developer.x.com/en/portal/products/pro or use alternative data sources.`); } throw new Error(formatTwitterError(error, 'searching tweets')); } throw error; } };
- src/tools.ts:79-102 (schema)MCP tool schema definition for searchTweets, including description and inputSchema used for tool listing and validation.searchTweets: { description: 'Search for tweets using a query string', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'The search query' }, maxResults: { type: 'number', description: 'Maximum number of results to return' }, tweetFields: { type: 'array', items: { type: 'string' }, description: 'Fields to include in the tweet objects' } }, required: ['query'] } },
- src/index.ts:313-316 (registration)Registration in the main server request handler: dispatches CallToolRequest for 'searchTweets' to the handleSearchTweets function.case 'searchTweets': { const { query, maxResults } = request.params.arguments as { query: string; maxResults?: number }; response = await handleSearchTweets(client, { query, maxResults }); break;
- src/types.ts:12-17 (schema)TypeScript interface defining the input arguments for searchTweets handler.export interface SearchTweetsArgs { query: string; since?: string; until?: string; tweetFields?: string[]; }
- src/index.ts:48-50 (registration)Import of the handleSearchTweets handler function into the main index.ts for use in tool dispatching.handleSearchTweets, handleHashtagAnalytics } from './handlers/search.handlers.js';