Skip to main content

Open Google MCP

A read-only Model Context Protocol (MCP) server for Google Ads (via GAQL), Search Console, Google Analytics 4, and Bing Webmaster Tools. Designed for AI assistants and LLM agents to safely read campaign performance, search analytics, website traffic, and more.

Open Google MCP: stop manually feeding data to your AI. Connect Google Ads, GA4, Search Console, and Bing Webmaster.

PyPI Python License: MIT

Quick start

uvx open-google-mcp

That downloads the server, runs it, and leaves your system alone. Point your MCP client at uvx open-google-mcp and paste your credentials into the env block. See Setup for the full config.

Prefer Docker or a git checkout? Both work. See Option B and Option C.

Tools

Google Ads

Tool Input Description
list_accessible_customers — Discover Google Ads account IDs
get_resource_metadata resource_name Explore selectable/filterable/sortable fields for a resource
search customer_id, resource, fields, conditions?, orderings?, limit? Execute read-only GAQL queries

Google Search Console

Tool Input Description
gsc_get_capabilities — Get categorized tool list with auth status
gsc_list_properties — List all GSC properties (start here)
gsc_get_site_details site_url Verification/ownership for a property
gsc_get_search_analytics site_url, days?, dimensions?, row_limit? Top queries with clicks, impressions, CTR, position
gsc_get_performance_overview site_url, days? Executive summary with daily trend
gsc_compare_search_periods site_url, period1_start/end, period2_start/end Compare two date ranges
gsc_get_advanced_search_analytics site_url, start_date?, end_date?, dimensions?, search_type?, row_limit?, start_row?, sort_by?, sort_direction?, filters? Filtered, sorted, paginated analytics
gsc_inspect_url site_url, page_url Debug a URL's crawl/index status
gsc_get_sitemaps site_url List sitemaps with status and errors

Google Analytics 4

Tool Input Description
ga4_get_capabilities — Get categorized tool list with auth status
ga4_list_properties — Discover all accessible GA4 properties
ga4_get_metadata property_id Browse available dimensions and metrics
ga4_run_report property_id, dimensions?, metrics?, start_date?, end_date?, filters?, order_bys?, limit? Run a standard report with filtering and ordering
ga4_run_realtime_report property_id, dimensions?, metrics?, limit? Get real-time data (last 30 minutes)

Google Keyword Planner

Tool Input Description
generate_keyword_ideas customer_id?, keywords?/url?, geos?, language?, network?, page_size? Keyword ideas with search volume, competition, bid ranges
generate_keyword_historical_metrics customer_id?, keywords, geos?, language? Historical metrics for exact keywords
generate_keyword_forecast_metrics customer_id?, keywords, match_types?, currency_code?, start/end_date?, budget/bid? Simulated campaign forecast (impressions, clicks, CPC, cost)
suggest_geo_target_constants names, country_code?, locale? Look up geo resource names (e.g. United States → geoTargetConstants/2840)

Keyword Planner tools reuse the same service account + developer token as the Ads tools. customer_id is optional — it falls back to GOOGLE_ADS_DEFAULT_CUSTOMER_ID, then GOOGLE_ADS_LOGIN_CUSTOMER_ID from .env. The account needs Keyword Planner access (Tools → Planning → Keyword Planner in Google Ads); manager (MCC) accounts usually don't have it — use a child customer ID. The developer token must have at least basic access (explorer-level tokens are rejected: "apply for basic or standard access" — ads.google.com → Tools → API Center → Request higher access).

Bing Webmaster Tools

Tool Input Description
bing_get_capabilities — Get tool list with auth status
bing_list_sites — List verified sites (start here)
bing_get_query_stats site_url, limit? Top queries with clicks, impressions, positions
bing_get_page_stats site_url, limit? Top pages with clicks, impressions, positions
bing_get_traffic_stats site_url, days? Daily clicks and impressions with totals
bing_get_query_pages site_url, query, limit? Pages ranking for one query
bing_get_page_queries site_url, page, limit? Queries a page ranks for
bing_get_url_info site_url, url Crawl and index details for one URL
bing_get_crawl_stats site_url Crawl volume and response codes
bing_get_crawl_issues site_url, limit? Indexing problems found by Bing
bing_get_link_counts site_url, page? Inbound link counts per page
bing_get_sitemaps site_url Submitted sitemaps and feeds
bing_keyword_stats query, country?, language? Historical keyword data
bing_get_related_keywords query, country?, language?, start/end_date?, limit? Related keyword discovery
seo_compare_google_bing bing_site_url, gsc_site_url, days?, limit? Join Google and Bing top queries

Bing tools use an API key — no OAuth and no service account. Bing updates query and page reports weekly. Traffic data updates daily. Query and page reports have no date-range filter.

Manager Account Auto-Routing

If search targets a manager (MCC) account and finds no data directly, it automatically:

  1. Detects the account is a manager
  2. Finds child accounts
  3. Runs the query on each child
  4. Returns combined results with _source_customer_id marking which account each row belongs to

Setup

Prerequisites

Google credentials are only needed for Google tools. Bing tools need only an API key.

Bing Webmaster Tools (optional)

Bing tools need one API key. No OAuth and no service account are required.

  1. Sign in at Bing Webmaster Tools.
  2. Add your site and verify ownership.
  3. Open Settings → API Access.
  4. Accept the terms and click Generate API Key.
  5. Add the key to .env:
    BING_WEBMASTER_API_KEY="your_key_here"
    

The key belongs to your user account. One key covers every verified site.


Credentials

A single service account authenticates Google Ads, Search Console, and Google Analytics 4.

  1. Go to GCP Console → APIs & Services → Credentials → Create Credentials → Service Account
  2. Download the JSON key file. You need five fields from it.
  3. Google Ads: add the service account email in your manager account (Settings → Account access → Service account users)
  4. Search Console: add the same email to your property (Settings → Users and permissions → Add user, grant Full access)
  5. Google Analytics 4: add the same email to your GA4 property (Admin → Account Access Management → Add user → Viewer)
Variable Description
GOOGLE_ADS_DEVELOPER_TOKEN Your Google Ads API developer token
GOOGLE_SERVICE_ACCOUNT_EMAIL Service account email
GOOGLE_SERVICE_ACCOUNT_KEY Private key (with \n newlines)
GOOGLE_SERVICE_ACCOUNT_KEY_ID Private key ID
GOOGLE_SERVICE_ACCOUNT_CLIENT_ID Client ID
GOOGLE_SERVICE_ACCOUNT_PROJECT_ID GCP project ID
GOOGLE_ADS_LOGIN_CUSTOMER_ID Optional — for MCC account routing
GOOGLE_ADS_DEFAULT_CUSTOMER_ID Optional — default customer_id for Keyword Planner tools (falls back to LOGIN_CUSTOMER_ID)
GA4_CREDENTIALS_PATH Optional — dedicated GA4 credential file
BING_WEBMASTER_API_KEY Optional — Bing Webmaster Tools API key
BING_CACHE_TTL Optional — Bing response cache in seconds (default: 300)
BING_REQUEST_TIMEOUT Optional — Bing HTTP timeout in seconds (default: 30)

Supply these variables one of two ways. Never commit them.

  • Client env block — used by the uvx install. That mode has no .env file.
  • .env file at the project root — used by the Docker and checkout installs.

uvx downloads the package into a cache and runs it. Nothing installs globally.

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

On macOS you can also run brew install uv. On Windows use winget install --id=astral-sh.uv -e.

2. Try it

uvx open-google-mcp

The server speaks MCP over stdio and waits for a client. A silent terminal is correct. Press Ctrl+C to stop.

The first run downloads dependencies and takes about a minute. Later runs start in under a second.

Without uv, pipx run open-google-mcp does the same job.

3. MCP client config

Put your credentials in the env block. Keep the \n escapes inside the private key.

Claude Desktop:

{
  "mcpServers": {
    "open-google-mcp": {
      "command": "uvx",
      "args": ["open-google-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token",
        "GOOGLE_SERVICE_ACCOUNT_EMAIL": "svc@project.iam.gserviceaccount.com",
        "GOOGLE_SERVICE_ACCOUNT_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n",
        "GOOGLE_SERVICE_ACCOUNT_KEY_ID": "key_id",
        "GOOGLE_SERVICE_ACCOUNT_CLIENT_ID": "client_id",
        "GOOGLE_SERVICE_ACCOUNT_PROJECT_ID": "your-project",
        "BING_WEBMASTER_API_KEY": "optional"
      }
    }
  }
}

opencode (opencode.json):

{
  "mcp": {
    "open-google-mcp": {
      "type": "local",
      "command": ["uvx", "open-google-mcp"],
      "environment": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token"
      },
      "enabled": true
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "open-google-mcp": {
      "command": "uvx",
      "args": ["open-google-mcp"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_token"
      }
    }
  }
}

Cursor (.cursor/mcp.json): same shape as the Claude Desktop block.


Option B: Docker (no Python required)

1. Clone

git clone https://github.com/ceotind/open-google-mcp.git
cd open-google-mcp

2. Configure .env

cp .env.example .env
# Edit .env with the service account values + developer token

3. Build and start the container (once)

docker compose build
docker compose up -d open-google-mcp

This starts a single long-lived container. Client configs attach to it with docker compose exec instead of docker compose run, so a new container is not created every session. (Don't use docker compose run for a client — it spawns a new container each launch and --rm never removes a long-running stdio server, so containers pile up.)

4. MCP client config

Claude Desktop:

{
  "mcpServers": {
    "open-google-mcp": {
      "command": "docker",
      "args": ["compose", "exec", "-T", "open-google-mcp", "python", "-m", "open_google_mcp"],
      "workdir": "/path/to/open-google-mcp"
    }
  }
}

opencode:

{
  "mcp": {
    "open-google-mcp": {
      "type": "local",
      "command": ["docker", "compose", "exec", "-T", "open-google-mcp", "python", "-m", "open_google_mcp"],
      "cwd": "/path/to/open-google-mcp",
      "enabled": true
    }
  }
}

Cursor:

  • Name: open-google-mcp
  • Type: command
  • Command: docker compose exec -T open-google-mcp python -m open_google_mcp
  • Working directory: /path/to/open-google-mcp

Option C: Python (local checkout)

Use this path to develop the server or pin it to a local commit.

1. Clone and install

git clone https://github.com/ceotind/open-google-mcp.git
cd open-google-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Configure .env

cp .env.example .env

The variables are the same as the Credentials table above.

3. Run

source .venv/bin/activate
source .env
python -m open_google_mcp

Or use the wrapper script. It loads .env for you:

./server.sh

4. MCP client config

Claude Desktop:

{
  "mcpServers": {
    "open-google-mcp": {
      "command": "/path/to/open-google-mcp/server.sh"
    }
  }
}

opencode:

{
  "mcp": {
    "open-google-mcp": {
      "type": "local",
      "command": ["/path/to/open-google-mcp/server.sh"],
      "enabled": true
    }
  }
}

Cursor:

  • Name: open-google-mcp
  • Type: command
  • Command: /path/to/open-google-mcp/server.sh

Google Ads — Usage Examples

List Ads accounts

list_accessible_customers

Discover fields for a resource

get_resource_metadata(resource_name="campaign")

Get active search campaigns with performance

search(
  customer_id="1234567890",
  resource="campaign",
  fields=["campaign.id", "campaign.name", "campaign.status",
          "campaign.advertising_channel_type", "metrics.clicks",
          "metrics.impressions", "metrics.cost_micros"],
  conditions=["campaign.status = 'ENABLED'",
              "segments.date DURING LAST_30_DAYS"],
  orderings=["metrics.clicks DESC"],
  limit=10
)

Get child accounts under a manager

search(
  customer_id="1234567890",
  resource="customer_client",
  fields=["customer_client.id", "customer_client.descriptive_name", "customer_client.manager"]
)

Google Search Console — Usage Examples

List GSC properties

gsc_list_properties

Get search analytics

gsc_get_search_analytics(
  site_url="https://example.com",
  days=28,
  dimensions="query",
  row_limit=10
)

Get performance overview

gsc_get_performance_overview(
  site_url="https://example.com",
  days=28
)

Compare two time periods

gsc_compare_search_periods(
  site_url="https://example.com",
  period1_start="2025-01-01",
  period1_end="2025-01-31",
  period2_start="2025-02-01",
  period2_end="2025-02-28",
  dimensions="query",
  limit=10
)

Advanced analytics with filters

gsc_get_advanced_search_analytics(
  site_url="https://example.com",
  dimensions="query,device",
  search_type="WEB",
  row_limit=50,
  sort_by="impressions",
  sort_direction="descending",
  filters='[{"dimension":"country","operator":"equals","expression":"usa"}]'
)

Inspect a URL

gsc_inspect_url(
  site_url="https://example.com",
  page_url="https://example.com/blog/post"
)

List sitemaps

gsc_get_sitemaps(site_url="https://example.com")

Google Analytics 4 — Usage Examples

Start here — discover properties

ga4_list_properties

Returns your property ID (e.g. 123456789) — use it in all other GA4 tools.

Browse available dimensions and metrics

ga4_get_metadata(property_id="123456789")

Returns 300+ dimensions and 100+ metrics available for reporting.

Run a basic report (property-level summary)

ga4_run_report(
  property_id="123456789",
  metrics="activeUsers,sessions,newUsers",
  start_date="28daysAgo",
  end_date="today"
)

Top countries by users

ga4_run_report(
  property_id="123456789",
  dimensions="country",
  metrics="activeUsers",
  start_date="28daysAgo",
  end_date="today",
  limit=10,
  order_bys=[{"metric": "activeUsers", "desc": true}]
)

Top pages with views

ga4_run_report(
  property_id="123456789",
  dimensions="pagePath",
  metrics="screenPageViews,activeUsers",
  start_date="28daysAgo",
  end_date="today",
  limit=10,
  order_bys=[{"metric": "screenPageViews", "desc": true}]
)

Traffic sources breakdown

ga4_run_report(
  property_id="123456789",
  dimensions="sessionDefaultChannelGrouping",
  metrics="activeUsers,sessions",
  start_date="28daysAgo",
  end_date="today",
  limit=10,
  order_bys=[{"metric": "activeUsers", "desc": true}]
)

Filter by country (e.g. only United States)

ga4_run_report(
  property_id="123456789",
  dimensions="city",
  metrics="activeUsers",
  start_date="28daysAgo",
  end_date="today",
  filters={"field": "country", "type": "string_filter",
           "value": "United States", "match_type": "EXACT"},
  limit=10
)

Device breakdown

ga4_run_report(
  property_id="123456789",
  dimensions="deviceCategory",
  metrics="activeUsers,sessions",
  start_date="28daysAgo",
  end_date="today"
)

Real-time report (last 30 minutes)

ga4_run_realtime_report(
  property_id="123456789",
  dimensions="country,deviceCategory",
  metrics="activeUsers",
  limit=10
)

Date formats

You can use relative or absolute dates:

  • Relative: today, yesterday, 7daysAgo, 28daysAgo, 30daysAgo
  • Absolute: 2026-01-01 (YYYY-MM-DD format)

Google Keyword Planner — Usage Examples

customer_id is optional everywhere — set GOOGLE_ADS_DEFAULT_CUSTOMER_ID in .env and omit it in calls.

Keyword ideas for a seed term

generate_keyword_ideas(
  keywords=["running shoes", "trail running shoes"],
  geos=["geoTargetConstants/2840"],   # United States — find via suggest_geo_target_constants
  language="english"
)

Historical metrics for exact keywords

generate_keyword_historical_metrics(
  keywords=["running shoes", "hiking boots"],
  geos=["geoTargetConstants/2840"]
)

Forecast a campaign for next month

generate_keyword_forecast_metrics(
  keywords=["running shoes", "trail running shoes"],
  match_types=["PHRASE", "EXACT"],
  currency_code="USD",
  daily_budget_micros=20000000,   # $20/day
  max_cpc_bid_micros=500000       # $0.50 max CPC
)

Find a geo constant

suggest_geo_target_constants(names=["United States"], country_code="US")

Bing Webmaster Tools — Usage Examples

Bing needs one API key. Set BING_WEBMASTER_API_KEY in .env. No OAuth flow runs.

Start here — list verified sites

bing_list_sites()

Use the exact url value from this response as site_url in every other Bing tool.

Top queries

bing_get_query_stats(site_url="https://example.com/", limit=50)

Top pages

bing_get_page_stats(site_url="https://example.com/", limit=50)

Daily traffic trend

bing_get_traffic_stats(site_url="https://example.com/", days=30)

Pages ranking for one query

bing_get_query_pages(site_url="https://example.com/", query="running shoes")

Queries for one page

bing_get_page_queries(site_url="https://example.com/", page="https://example.com/classes")

Inspect a URL

bing_get_url_info(site_url="https://example.com/", url="https://example.com/classes")

Crawl issues

bing_get_crawl_issues(site_url="https://example.com/", limit=50)

Submitted sitemaps

bing_get_sitemaps(site_url="https://example.com/")

Keyword data

bing_keyword_stats(query="running shoes", country="us", language="en-US")
bing_get_related_keywords(query="running shoes", country="us", language="en-US")

Use IETF language tags like en-US, en-GB, or ja-JP. Bing rejects a bare code like en. The client adds the country when the tag has no region.

bing_get_related_keywords defaults to the last 30 days. Bing may return an empty list for low-volume terms.

Compare Google and Bing

seo_compare_google_bing(
  bing_site_url="https://example.com/",
  gsc_site_url="sc-domain:example.com",
  days=28,
  limit=25
)

The comparison joins queries by normalized text. It returns shared queries with click gaps. It also returns queries that appear on only one engine.

Bing data limits

  • Query and page reports are top-N snapshots.
  • Bing refreshes those reports weekly.
  • No date-range filter exists for query or page data.
  • bing_get_traffic_stats is the only daily series.
  • New or low-traffic sites may return empty rows until Bing collects data.
  • Responses are cached for 5 minutes to protect the daily quota.

GAQL Tips

  • Field names must be fully qualified: campaign.id, not id
  • Date format: YYYY-MM-DD with dashes
  • Relative dates: DURING LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, THIS_QUARTER
  • For change_event resource, limit must be ≤ 10000
  • Conditions are AND-combined
  • Use get_resource_metadata first to discover valid fields

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest          # unit tests — no network or credentials required

The Keyword Planner logic lives in src/open_google_mcp/keyword_planner.py (pure request builders and result flatteners, fully unit-tested). A live smoke test against the real API is available:

source .env && python scripts/smoke_keyword_planner.py [customer_id]

The Bing transport and normalization logic lives in src/open_google_mcp/bing_client.py. Its tests use httpx.MockTransport, so they need no network and no key.

License

MIT

Metadata

Release files for open-google-mcp 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for open-google-mcp 0.2.1
File Size Uploaded Provenance Actions
open_google_mcp-0.2.1.tar.gz 43.9 kB With provenance Details for open_google_mcp-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for open-google-mcp 0.2.1
File Interpreter ABI Platform Actions
open_google_mcp-0.2.1-py3-none-any.whl Python 3 none any Details for open_google_mcp-0.2.1-py3-none-any.whl

Total release size: 84.4 kB

Release files / open_google_mcp-0.2.1.tar.gz

Download URL open_google_mcp-0.2.1.tar.gz
Size 43.9 kB
Tags Source
SHA-256 checksum
How to use checksums
74d5c8fa01941e7165ae5a506c4c3c75ae549bf61ef4d733837e4bec90a2807f
BLAKE2b-256 checksum
How to use checksums
d3ef6126ecc9645b8c21f831e55f963d02b72c7546c2a280a4c1d48739da29e0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / open_google_mcp-0.2.1-py3-none-any.whl

Download URL open_google_mcp-0.2.1-py3-none-any.whl
Size 40.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07802fb600f6936d06cde5fe7c9adcc29cef3cfb779e89f018e2ce44ef666d38
BLAKE2b-256 checksum
How to use checksums
f3f409b47cb1837aa64f622bd4875b3076e58761779d986dbdeb23d4703616fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for open-google-mcp 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for open_google_mcp-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page