# ads-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that puts your mobile ad revenue in one conversational interface: **Google AdMob** and **Huawei Petal Ads** (Publisher Service), side by side.

Ask Claude things like:

```
"How much did I earn across AdMob and Petal Ads last week?"
"Which AdMob ad units are underperforming?"
"Break down my Petal Ads revenue by app"
"Compare yesterday's eCPM by country"
```

## Tools

| Tool | Network | Description |
|------|---------|-------------|
| `admob_list_accounts` | AdMob | List publisher accounts |
| `admob_get_account` | AdMob | Account details (currency, timezone) |
| `admob_list_apps` | AdMob | List apps (paginated) |
| `admob_list_ad_units` | AdMob | List ad units (paginated) |
| `admob_network_report` | AdMob | Network report with full dimension/metric/filter/sort control |
| `admob_mediation_report` | AdMob | Mediation report (per ad-source performance) |
| `petal_report` | Petal Ads | Publisher report with full group-by/filter/order/pagination control |
| `petal_revenue_summary` | Petal Ads | Daily earnings trend + totals for a date range |
| `petal_apps_performance` | Petal Ads | Per-app (and per-placement) earnings breakdown |
| `ads_revenue_overview` | Both | Combined totals + daily breakdown across both networks |
| `ads_auth_status` | Both | Check which networks are configured/authorized |

All tools are read-only — this server never mutates your ad accounts.

## Prerequisites

- Node.js 18+
- For AdMob: a Google Cloud project with the **AdMob API** enabled and an OAuth 2.0 **Desktop app** client
- For Petal Ads: a HUAWEI Developers OAuth client with the **Publisher Service Reporting API** (Ads Kit) enabled

## Setup

### 1. Install and build

```bash
git clone https://github.com/qalvinahmad/ads-mcp.git
cd ads-mcp
npm install
npm run build
cp .env.example .env
```

### 2. Google AdMob

1. Open [Google Cloud Console](https://console.cloud.google.com/) → select/create a project.
2. Enable the **AdMob API** in the API Library.
3. **APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app**, then download the JSON.
4. Save it as `secrets/client_secret.json` (or point `ADMOB_CLIENT_SECRET_PATH` in `.env` at it).
5. Run the one-time authorization (opens a browser):

```bash
npm run auth:admob
```

> If your OAuth consent screen is in "Testing" status, add your Google account as a test user (otherwise you'll get an authorization error, and refresh tokens expire after 7 days).

### 3. Huawei Petal Ads

1. Open [HUAWEI Developers Console](https://developer.huawei.com/consumer/en/console) → **HMS API Services → Credentials**.
2. Create an **OAuth 2.0 client ID** (server type) with the Ads Kit / Publisher Service Reporting API enabled.
3. Put the credentials in `.env`:

```env
HUAWEI_CLIENT_ID=your_client_id
HUAWEI_CLIENT_SECRET=your_client_secret
```

Or, if you keep them as a single combined key:

```env
HUAWEI_ADS_API_KEY=client_id:client_secret
```

No browser flow is needed — Petal Ads uses OAuth client-credentials (server-to-server).

### 4. Verify

```bash
npm run doctor    # checks both networks; tests the Huawei token endpoint
npm run smoke     # boots the server and validates the MCP handshake + tool list
```

## Register with an MCP client

### Claude Code (CLI)

```bash
claude mcp add ads -- node /absolute/path/to/ads-mcp/dist/index.js
```

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ads": {
      "command": "node",
      "args": ["/absolute/path/to/ads-mcp/dist/index.js"]
    }
  }
}
```

### Cursor / Windsurf / Cline

```json
"ads": {
  "command": "node",
  "args": ["/absolute/path/to/ads-mcp/dist/index.js"]
}
```

Configuration is read from `ads-mcp/.env` automatically (the server resolves it relative to its own install directory, not the client's working directory).

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ADMOB_CLIENT_SECRET_PATH` | `secrets/client_secret.json` | Google OAuth Desktop-app client JSON |
| `ADMOB_TOKEN_PATH` | `secrets/admob-token.json` | Cached authorized user token |
| `ADMOB_OAUTH_PORT` | `8089` | Localhost port for the one-time OAuth flow |
| `HUAWEI_CLIENT_ID` / `HUAWEI_CLIENT_SECRET` | — | Huawei OAuth client (preferred) |
| `HUAWEI_ADS_API_KEY` | — | Combined `client_id:client_secret` fallback |
| `HUAWEI_DEFAULT_CURRENCY` | `USD` | Default report currency (CNY, USD, EUR) |
| `HUAWEI_OAUTH_TOKEN_URL` | Huawei production | Override for testing |
| `HUAWEI_ADS_REPORT_URL` | Huawei production | Override for testing |

## Security notes

- `secrets/` and `.env` are gitignored — never commit credentials.
- The AdMob token file is written with `0600` permissions.
- Huawei access tokens are cached in memory only.
- All tools are read-only against both ad networks.

## API references

- [AdMob API v1](https://developers.google.com/admob/api/v1/getting-started) (`admob.googleapis.com/v1`)
- [Petal Ads Publisher Service Reporting API](https://developer.huawei.com/consumer/en/doc/development/HMSCore-References/query-publisher-service-reports-0000001050933546) (`ads.cloud.huawei.com/openapi/monetization/reports/v1/publisher`)

## Credits

- AdMob client and OAuth flow adapted from [willhou/admob-mcp](https://github.com/willhou/admob-mcp) (MIT).
- Petal Ads integration follows the official [HMS-Core/hms-ads-severdemo](https://github.com/HMS-Core/hms-ads-severdemo) reference.

## License

MIT — see [LICENSE](LICENSE).