Twitter MCP Server

Instructions

Implementation Reference

• src/index.ts:149-175 (handler)

  MCP tool handler for 'search_tweets': validates arguments using schema, calls TwitterClient.searchTweets, formats response.

  private async handleSearchTweets(args: unknown) {
    const result = SearchTweetsSchema.safeParse(args);
    if (!result.success) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Invalid parameters: ${result.error.message}`
      );
    }
  
    const { tweets, users } = await this.client.searchTweets(
      result.data.query,
      result.data.count
    );
  
    const formattedResponse = ResponseFormatter.formatSearchResponse(
      result.data.query,
      tweets,
      users
    );
  
    return {
      content: [{
        type: 'text',
        text: ResponseFormatter.toMcpResponse(formattedResponse)
      }] as TextContent[]
    };
  }

• src/twitter-api.ts:42-80 (helper)

  Core implementation of tweet search using Twitter API v2, including rate limiting, field expansions, data mapping to Tweet and TwitterUser types.

  async searchTweets(query: string, count: number): Promise<{ tweets: Tweet[], users: TwitterUser[] }> {
    try {
      const endpoint = 'tweets/search';
      await this.checkRateLimit(endpoint);
  
      const response = await this.client.v2.search(query, {
        max_results: count,
        expansions: ['author_id'],
        'tweet.fields': ['public_metrics', 'created_at'],
        'user.fields': ['username', 'name', 'verified']
      });
  
      console.error(`Fetched ${response.tweets.length} tweets for query: "${query}"`);
  
      const tweets = response.tweets.map(tweet => ({
        id: tweet.id,
        text: tweet.text,
        authorId: tweet.author_id ?? '',
        metrics: {
          likes: tweet.public_metrics?.like_count ?? 0,
          retweets: tweet.public_metrics?.retweet_count ?? 0,
          replies: tweet.public_metrics?.reply_count ?? 0,
          quotes: tweet.public_metrics?.quote_count ?? 0
        },
        createdAt: tweet.created_at ?? ''
      }));
  
      const users = response.includes.users.map(user => ({
        id: user.id,
        username: user.username,
        name: user.name,
        verified: user.verified ?? false
      }));
  
      return { tweets, users };
    } catch (error) {
      this.handleApiError(error);
    }
  }

• src/types.ts:21-27 (schema)

  Zod schema defining input validation for search_tweets tool arguments (query and count).

  export const SearchTweetsSchema = z.object({
      query: z.string().min(1, 'Search query cannot be empty'),
      count: z.number()
          .int('Count must be an integer')
          .min(10, 'Minimum count is 10')
          .max(100, 'Maximum count is 100')
  });

• src/index.ts:85-104 (registration)

  Registration of 'search_tweets' tool in MCP ListToolsRequestHandler, defining name, description, and input schema.

  {
    name: 'search_tweets',
    description: 'Search for tweets on Twitter',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query'
        },
        count: {
          type: 'number',
          description: 'Number of tweets to return (10-100)',
          minimum: 10,
          maximum: 100
        }
      },
      required: ['query', 'count']
    }
  } as Tool