# Google Ads Model Context Protocol (MCP) Server

This is a Model Context Protocol (MCP) server that enables AI assistants (such as Gemini, ChatGPT, Claude, and Cursor) to manage, report, and analyze Google Ads campaigns securely.

It features an encrypted database storage for managing multiple client accounts, real-time Google Ads API integrations, and robust audit trail logging.

---

## Features

- **Campaign Reporting:** Query campaigns, budgets, keywords, search terms, ads, conversions, audience, and device performance metrics.
- **Campaign Mutations:** Create campaigns, update budgets (with dry-run support), pause/resume campaigns, and add keywords or negative keywords.
- **Account Diagnostics:** Automated account analysis to identify issues like budget constraints and list actionable optimization recommendations.
- **Cross-Client Performance Comparison:** Compare metrics (Clicks, Cost, Conversions, CPA, ROAS) across all client accounts connected to the agency.
- **Encrypted Multi-Client Credentials:** Securely store and encrypt OAuth refresh tokens in Supabase using AES-256-GCM.
- **Dual Transport Mode:** Supports local command-line execution (`stdio`) and cloud-ready hosting (`Streamable HTTP / SSE`).
- **Comprehensive Audit Trails:** Automatically logs every tool execution (reads and writes) to Supabase for enterprise compliance.

---

## Setup & Local Development

### 1. Installation
Clone the repository and install dependencies:
```bash
npm install
```

### 2. Configure Environment Variables
Copy `.env.example` to a new file named `.env` and fill in your keys:
```ini
MOCK_MODE=false

# Supabase Configurations
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-service-role-key
ENCRYPTION_KEY=your-32-character-encryption-key-here

# Google Ads API Credentials (from Google Cloud Console & Ads Manager Account)
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-client-secret
GOOGLE_DEVELOPER_TOKEN=your-google-ads-developer-token
```
> **Note:** Set `MOCK_MODE=true` to test the server with simulated in-memory data without requiring Google Ads API credentials.

### 3. Generate OAuth Refresh Token
To allow the server to access a client's Google Ads account, run the OAuth helper script:
```bash
npx tsx src/utils/authHelper.ts
```
1. Click the generated link to open the browser.
2. Sign in with the client's Google account and grant **Google Ads** permissions.
3. The script will output a **Refresh Token** in your terminal.

### 4. Register a Client
Save and encrypt the client's details in your Supabase database:
```bash
npx tsx src/utils/registerClient.ts <google_customer_id> "<client_name>" "<refresh_token>"
```
*Example:*
```bash
npx tsx src/utils/registerClient.ts 181-756-0637 "nexusdatabase" "1//0gL0Srx..."
```

---

## Running the Server

### Stdio Mode (Default Local)
To run the server locally on your machine (for Cursor, Claude Desktop, or Gemini CLI):
```bash
# Build TypeScript
npm run build

# Start server
npm start
```

### Remote / Cloud Mode (Streamable HTTP / SSE)
Whenever a `PORT` environment variable is defined, the server will automatically start as a web server listening on `/mcp`.
```bash
$env:PORT="8080"
npm start
```
The server will now be accessible at `http://0.0.0.0:8080/mcp`.

---

## Testing

Run the automated mock test suite to verify that all reporting, mutation, diagnostics, and database functions are working correctly:
```bash
npm test
```

---

## Cloud Deployment

You can host this server on any cloud platform supporting Node.js (e.g., **Render**, **Railway**, or **Heroku**).

1. Connect this repository to your hosting provider.
2. Configure the following deployment commands:
   - **Build Command:** `npm install && npm run build`
   - **Start Command:** `npm start`
3. Add your environment variables (from `.env`) in your cloud provider's dashboard.
4. Connect your AI client (like Cursor or ChatGPT) directly using the hosted URL (e.g. `https://your-app-name.render.com/mcp`).