# AdMob MCP Server

This is a server that exposes the [Google AdMob API](https://developers.google.com/admob/api) as a set of tools for the Model Context Protocol (MCP).

> **Disclaimer:** This is an independent, community-built project and is not an official Google product. It is not affiliated with, endorsed by, or supported by Google.

## Prerequisites

*   Node.js
*   npm

## Installation

1.  Clone the repository:
    ```bash
    git clone https://github.com/kunny/admob-mcp-server.git
    cd admob-mcp-server
    ```

2.  Install the dependencies:
    ```bash
    npm install
    ```

3.  Build the server:
    ```bash
    npm run build
    ```

## Configuration

1.  **Enable the AdMob API**

    a. Go to the [Google API Console](https://console.developers.google.com/apis/library).

    b. From the projects list, select a project or create a new one.

    c. In the API Library, search for "AdMob API".

    d. Select "AdMob API" and click the "Enable" button.

2.  **Create OAuth 2.0 Credentials**

    a. Go to the [Credentials page](https://console.developers.google.com/apis/credentials) in the Google API Console.

    b. Click "Create Credentials" and select "OAuth client ID".

    c. Select "Desktop app" for the "Application type".

    d. Enter a name for the credential (e.g., "AdMob MCP Server").

    e. Click "Create".

    f. A "Client ID" and "Client Secret" will be displayed. Click "Download JSON" to download the client secret file.

3.  **Set up the Credentials**

    a. Create a `credentials` directory in the root of the project:
    ```bash
    mkdir credentials
    ```

    b. Move the downloaded JSON file to the `credentials` directory and rename it to `client_secret.json`.

4.  **Set the Publisher Code (Optional)**

    Create a `.env` file in the root of the project and add your AdMob publisher ID:
    ```
    PUBLISHER_CODE=pub-xxxxxxxxxxxxxxxx
    ```

5.  **Select the API Endpoint (Optional)**

    The server talks to the AdMob REST API directly, so the endpoint and API
    version are configurable. Both are optional and default to the public
    production API.

    ```
    # Base URL of the AdMob API (no version segment, no trailing slash).
    # Default: https://admob.googleapis.com
    # Example test endpoint: https://xxx.sandbox.googleapis.com
    ADMOB_API_ENDPOINT=https://admob.googleapis.com

    # API version segment. Default: v1 (use v1beta for preview features).
    ADMOB_API_VERSION=v1
    ```

## Authentication

Run the following command to authenticate with your Google account:

```bash
npm run auth
```

This will open a browser window for you to log in and grant permission to the application.

After you have authenticated, a `token.json` file will be created in the `credentials` directory.

## Running the Server

To start the server, run the following command:

```bash
npm start
```

The server will be running on `stdio`.

## Capabilities

### Prompts

*  `top_performing_apps_last7d`: List top performing apps in the last 7 days, sorted by estimated earnings.
*  `top_performing_ad_units_last7d`: Lists top performing ad units with estimated earnings for all mediated networks over the last 7 days, sorted by estimated earnings.

### Tools

*   `generate_network_report`: Generates an AdMob Network report based on the provided report specification.
*   `generate_mediation_report`: Generates an AdMob Mediation report based on the provided report specification.
*   `get_account`: Gets information about the AdMob publisher account.
*   `list_ad_units`: Lists the ad units under the AdMob publisher account.
*   `list_apps`: Lists the apps under the AdMob publisher account.

## Usage with AI Agents

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "admob": {
      "command": "node",
      "args": [
        "{PATH_TO_SERVER}/build/index.js"
      ],
      "env": {
        "CREDENTIALS_DIR": "{PATH_TO_SERVER}/credentials",
        "PUBLISHER_CODE": "pub-xxxxxxx",
        "ADMOB_API_ENDPOINT": "https://admob.googleapis.com",
        "ADMOB_API_VERSION": "v1"
      }
    }
  }
}
```

### Gemini CLI

Add to your `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "admob": {
      "command": "node",
      "args": [
        "{PATH_TO_SERVER}/build/index.js"
      ],
      "env": {
        "CREDENTIALS_DIR": "{PATH_TO_SERVER}/credentials",
        "PUBLISHER_CODE": "pub-xxxxxxx",
        "ADMOB_API_ENDPOINT": "https://admob.googleapis.com",
        "ADMOB_API_VERSION": "v1"
      }
    }
  }
}
```

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.