searchTweets
Search for tweets on Twitter by entering a query string, specify maximum results, and include specific tweet fields to retrieve targeted data efficiently.
Instructions
Search for tweets using a query string
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of results to return | |
| query | Yes | The search query | |
| tweetFields | No | Fields to include in the tweet objects |
Implementation Reference
- src/handlers/search.handlers.ts:23-58 (handler)Main handler function that executes the searchTweets tool logic using Twitter API v2 search endpoint, formats results with authors, and handles errors including tier requirements.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)Input schema and description for the searchTweets tool, defining parameters like query (required), maxResults, and tweetFields for MCP tool registration.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)Tool dispatch/execution registration in the main server request handler switch statement, calling handleSearchTweets with parsed arguments.case 'searchTweets': { const { query, maxResults } = request.params.arguments as { query: string; maxResults?: number }; response = await handleSearchTweets(client, { query, maxResults }); break;
- src/index.ts:104-109 (registration)Registration of all tools including searchTweets via the TOOLS object in the ListToolsRequestSchema handler.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: Object.entries(TOOLS).map(([name, tool]) => ({ name, ...tool })) }));