Content
# Google Ads MCP Server (Experimental)
This repo contains the source code for running a local
[MCP](https://modelcontextprotocol.io) server that interacts with the
[Google Ads API](https://developers.google.com/google-ads/api).
## Tools
The server uses the
[Google Ads API](https://developers.google.com/google-ads/api/reference/rpc/v21/overview)
to provide several
[Tools](https://modelcontextprotocol.io/docs/concepts/tools) for use with LLMs.
### Tools available
- `search`: Retrieves information about the Google Ads account.
- `list_accessible_customers`: Returns names of customers directly accessible
by the user authenticating the call.
## Notes
1. The MCP Server will expose your data to the Agent or LLM that you connect to it.
1. If you have technical isses, please use the [GitHub issue tracker](https://github.com/googleads/google-ads-mcp/issues).
1. To help us collect usage data, you will notice an extra header has been added to your API calls, this data is used to improve the product.
## Setup instructions
Setup involves the following steps:
1. Configure Python.
1. Configure Developer Token.
1. Enable APIs in your project
1. Configure Credentials.
1. Configure Gemini.
### Configure Python
[Install pipx](https://pipx.pypa.io/stable/#install-pipx).
### Configure Developer Token
Follow the instructions for [Obtaining a Developer Token](https://developers.google.com/google-ads/api/docs/get-started/dev-token).
Record 'YOUR_DEVELOPER_TOKEN', you will need this for the the 'Configure Gemini' step below
### Enable APIs in your project
[Follow the instructions](https://support.google.com/googleapi/answer/6158841)
to enable the following APIs in your Google Cloud project:
* [Google Ads API](https://console.cloud.google.com/apis/library/googleads.googleapis.com)
### Configure Credentials
#### Option 1: Configure credentials using Application Default Credentials
Configure your [Application Default Credentials
(ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc).
Make sure the credentials are for a user with access to your Google Ads
accounts or properties.
Credentials must include the Google Ads API scope:
```
https://www.googleapis.com/auth/adwords
```
Check out
[Manage OAuth Clients](https://support.google.com/cloud/answer/15549257)
for how to create an OAuth client.
Here are some sample `gcloud` commands you might find useful:
- Set up ADC using user credentials and an OAuth desktop or web client after
downloading the client JSON to `YOUR_CLIENT_JSON_FILE`.
```shell
gcloud auth application-default login \
--scopes https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
--client-id-file=YOUR_CLIENT_JSON_FILE
```
- Set up ADC using service account impersonation.
```shell
gcloud auth application-default login \
--impersonate-service-account=SERVICE_ACCOUNT_EMAIL \
--scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform
```
When the `gcloud auth application-default` command completes, copy the
`PATH_TO_CREDENTIALS_JSON` file location printed to the console in the
following message. You will need this for a later step!
```
Credentials saved to file: [PATH_TO_CREDENTIALS_JSON]
```
#### Option 2: Configure credentials using the Google Ads API Python client library.
[Follow the instructions](https://developers.google.com/google-ads/api/docs/client-libs/python/)
to setup and configure the Google Ads API Python client library
If you have already done this and have a working `google-ads.yaml` , you can reuse this file!
In the utils.py file, change get_googleads_client() to use the load_from_storage() method.
### Configure Gemini
1. Install [Gemini
CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/index.md)
or [Gemini Code
Assist](https://marketplace.visualstudio.com/items?itemName=Google.geminicodeassist)
1. Create or edit the file at `~/.gemini/settings.json`, adding your server
to the `mcpServers` list.
- Option 1: the Application Default Credentials method
Replace `PATH_TO_CREDENTIALS_JSON` with the path you copied in the previous
step.
We also recommend that you add a `GOOGLE_CLOUD_PROJECT` attribute to the
`env` object. Replace `YOUR_PROJECT_ID` in the following example with the
[project ID](https://support.google.com/googleapi/answer/7014113) of your
Google Cloud project.
```json
{
"mcpServers": {
"google-ads-mcp": {
"command": "pipx",
"args": [
"run",
"--spec",
"git+https://github.com/googleads/google-ads-mcp.git",
"google-ads-mcp"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
"GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
"GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
}
}
}
}
```
- Option 2: the Python client library method
```json
{
"mcpServers": {
"google-ads-mcp": {
"command": "pipx",
"args": [
"run",
"--spec",
"git+https://github.com/googleads/google-ads-mcp.git",
"google-ads-mcp"
],
"env": {
"GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
"GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN"
}
}
}
}
```
#### Login Customer Id
If your access to the customer account is through a manager account, you will
need to add the customer ID of the manager account to the settings file.
See [here](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid) for details.
The final file will look like this:
```json
{
"mcpServers": {
"google-ads-mcp": {
"command": "pipx",
"args": [
"run",
"--spec",
"git+https://github.com/googleads/google-ads-mcp.git",
"google-ads-mcp"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "PATH_TO_CREDENTIALS_JSON",
"GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID",
"GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
"GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_CUSTOMER_ID"
}
}
}
}
```
## Try it out
Launch Gemini Code Assist or Gemini CLI and type `/mcp`. You should see
`google-ads-mcp` listed in the results.
Here are some sample prompts to get you started:
- Ask what the server can do:
```
what can the ads-mcp server do?
```
- Ask about customers:
```
what customers do I have access to?
```
- Ask about campaigns
```
How many active campaigns do I have?
```
```
How is my campaign performance this week?
```
### Note about Customer ID
Your agent will need and ask for a customer id for most prompts. If you are
moving between multiple customers, including the customer ID in the prompt may
be simpler.
```
How many active campaigns do I have for customer id 1234567890
```
## Contributing
Contributions welcome! See the [Contributing Guide](CONTRIBUTING.md).
