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.
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:
- Detects the account is a manager
- Finds child accounts
- Runs the query on each child
- Returns combined results with
_source_customer_idmarking which account each row belongs to
Setup
Prerequisites
Google credentials are only needed for Google tools. Bing tools need only an API key.
- Bing only: a Bing Webmaster Tools API key (see below).
- Google Ads: a developer token (apply via Google Ads API Center).
- Google Cloud: a service account with the following APIs enabled:
Bing Webmaster Tools (optional)
Bing tools need one API key. No OAuth and no service account are required.
- Sign in at Bing Webmaster Tools.
- Add your site and verify ownership.
- Open Settings → API Access.
- Accept the terms and click Generate API Key.
- 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.
- Go to GCP Console → APIs & Services → Credentials → Create Credentials → Service Account
- Download the JSON key file. You need five fields from it.
- Google Ads: add the service account email in your manager account (Settings → Account access → Service account users)
- Search Console: add the same email to your property (Settings → Users and permissions → Add user, grant Full access)
- 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
envblock — used by theuvxinstall. That mode has no.envfile. .envfile at the project root — used by the Docker and checkout installs.
Option A: uvx (recommended — no clone, no Python setup)
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 execinstead ofdocker compose run, so a new container is not created every session. (Don't usedocker compose runfor a client — it spawns a new container each launch and--rmnever 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_statsis 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, notid - Date format:
YYYY-MM-DDwith dashes - Relative dates:
DURING LAST_7_DAYS,LAST_30_DAYS,THIS_MONTH,THIS_QUARTER - For
change_eventresource, limit must be ≤ 10000 - Conditions are AND-combined
- Use
get_resource_metadatafirst 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.