google-trends-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Google Trends MCP (Model Context Protocol) server that provides access to Google Trends data through the RapidAPI Google Trends Scraper API. The server implements three main endpoints:

1. Status: Check API health and status
2. Questions: Get trending questions from Google Trends
3. Trending: Get currently trending topics from Google Trends

Commands

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode with auto-reload
npm run dev

# Run the compiled server
npm start

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only
npm run test:watch        # Watch mode

# Run tests with coverage
npm test -- --coverage

# Run a single test file
npm test -- tests/integration/search.test.ts

# Run tests matching a pattern
npm test -- --testNamePattern="should search for"

# Run tests with single worker (useful for debugging)
npm test -- --maxWorkers=1

Architecture

MCP Server Structure

The server is built using the Model Context Protocol SDK and follows this pattern:

1. Main Server Class (src/index.ts): GoogleTrendsMcpServer encapsulates all functionality

   • Uses StdioServerTransport for communication
   • Registers handlers for ListToolsRequestSchema and CallToolRequestSchema
   • Each tool handler makes API calls and returns formatted responses

2. API Integration Pattern:

   • makeApiRequest(): Centralized method for all API calls with consistent headers
   • Each handler (status, questions, trending) follows the same pattern:
     • Make API request to Google Trends API
     • Normalize response to match TypeScript types
     • Return formatted MCP response

3. Type System (src/types.ts):

   • Separate interfaces for parameters (StatusParams, QuestionsParams, TrendingParams)
   • Response types for Google Trends data structures
   • Flexible types to accommodate API response variations