@andrewlwn77/google-trends-mcp/README.md

MCP server for Google Trends API integration - Access trending topics, questions, and search data

# Google Trends MCP Server

[![npm version](https://badge.fury.io/js/%40andrewlwn77%2Fgoogle-trends-mcp.svg)](https://www.npmjs.com/package/@andrewlwn77/google-trends-mcp)

⚠️ **IMPORTANT SECURITY NOTICE**: Never commit API keys to version control. This package requires an API key to be set via environment variable.

An MCP (Model Context Protocol) server that provides access to Google Trends data through the Google Trends Scraper API.

## Features

- **Status**: Check the API status and health
- **Questions**: Get trending questions from Google Trends
- **Trending**: Get currently trending topics from Google Trends

## Installation

### Option 1: Using npx (Recommended)
```bash
# Set your API key first
export GOOGLE_TRENDS_API_KEY="your-api-key-here"

# Run directly with npx
npx @andrewlwn77/google-trends-mcp
```

### Option 2: Global Installation
```bash
npm install -g @andrewlwn77/google-trends-mcp
```

### Option 3: Local Development
```bash
git clone <repository-url>
cd google-trends-mcp
npm install
npm run build
```

## Configuration

**Optional**: You can set the `GOOGLE_TRENDS_API_KEY` environment variable. If not set, a default API key will be used.

1. Get an API key from [RapidAPI Google Trends Scraper](https://rapidapi.com/google-trends-scraper1/api/google-trends-scraper1)
2. Set the environment variable:
   ```bash
   # Option 1: Export in your shell
   export GOOGLE_TRENDS_API_KEY="your-api-key-here"
   
   # Option 2: Create a .env file (for local development)
   echo "GOOGLE_TRENDS_API_KEY=your-api-key-here" > .env
   ```

⚠️ **Security**: Never commit your `.env` file or API key to version control!

## Usage

### Running the server

```bash
# If installed globally or using npx
google-trends-mcp

# For local development
npm start

# For development with auto-reload
npm run dev
```

### Available Tools

#### 1. `google_trends_status`
Check the status of the Google Trends API.

**Parameters:**
- `language` (optional): Language code (default: "en")
- `country` (optional): Country code (default: "US")

#### 2. `google_trends_questions`
Get trending questions from Google Trends.

**Parameters:**
- `language` (optional): Language code (default: "en")
- `country` (optional): Country code (default: "US")

#### 3. `google_trends_trending`
Get currently trending topics from Google Trends.

**Parameters:**
- `language` (optional): Language code (default: "en")
- `country` (optional): Country code (default: "US")

### Example Usage with MCP Client

```typescript
// Check API status
const status = await client.callTool('google_trends_status', {
  language: 'en',
  country: 'US'
});

// Get trending questions
const questions = await client.callTool('google_trends_questions', {
  language: 'en',
  country: 'US'
});

// Get trending topics
const trending = await client.callTool('google_trends_trending', {
  language: 'en',
  country: 'US'
});
```

## Configuration

The server can be configured using environment variables:

- `GOOGLE_TRENDS_API_KEY`: Your RapidAPI key for the Google Trends Scraper API (optional, defaults to example key)

## Development

### Project Structure

```
google-trends-mcp/
├── src/
│   ├── index.ts      # Main MCP server implementation
│   └── types.ts      # TypeScript type definitions
├── tests/
│   ├── integration/  # API integration tests
│   ├── unit/         # Unit tests
│   └── helpers/      # Test helper utilities
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
```

### Type Safety

This server is written in TypeScript and provides full type safety for:
- API parameters
- API responses
- Error handling
- Google Trends data structures

## License

MIT