Skip to main content
Glama
flin-agency

flin-google-keyword-planner-mcp

by flin-agency
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

flin-google-keyword-planner-mcp

MCP server for Google Ads Keyword Planner ideas.

This server exposes focused read-only tools so an LLM can clearly choose the right seed strategy.

Exposed MCP tools

  • keyword_ideas_from_keywords

  • keyword_ideas_from_url

  • keyword_ideas_from_keyword_and_url

  • keyword_ideas_from_site

  • keyword_ideas_historical

Related MCP server: google-ads-write-mcp

Tool overview

1) keyword_ideas_from_keywords

Generate ideas from a keyword list (KeywordSeed).

Required:

  • keywords

2) keyword_ideas_from_url

Generate ideas from a page URL (UrlSeed).

Required:

  • url

3) keyword_ideas_from_keyword_and_url

Generate ideas from keyword list + URL (KeywordAndUrlSeed).

Required:

  • keywords

  • url

4) keyword_ideas_from_site

Generate ideas from a full site/domain (SiteSeed).

Required:

  • site_url

5) keyword_ideas_historical

Generate ideas from keywords and constrain historical metrics to a year-month range.

Required:

  • keywords

  • start_year

  • start_month

  • end_year

  • end_month

Historical option:

  • include_average_cpc (default false)

Common optional parameters (all tools)

  • customer_id

  • language_id (default 1000)

  • location_ids (default 2840 = US)

  • network (GOOGLE_SEARCH or GOOGLE_SEARCH_AND_PARTNERS)

  • include_adult_keywords (default false)

  • limit (default 50, max 1000)

  • page_token

  • keyword_annotation (currently: KEYWORD_CONCEPT)

  • aggregate_metric_types (currently: DEVICE)

  • login_customer_id

Requirements

  1. Python 3.10+

  2. Google Ads API credentials:

  • GOOGLE_ADS_DEVELOPER_TOKEN

  • GOOGLE_ADS_CLIENT_ID

  • GOOGLE_ADS_CLIENT_SECRET

Optional:

  • GOOGLE_ADS_REFRESH_TOKEN (only needed if you want a persistent token instead of generating one in Claude)

  • GOOGLE_ADS_LOGIN_CUSTOMER_ID

  • GOOGLE_ADS_CUSTOMER_ID (default customer if no customer_id argument is passed)

  • GOOGLE_ADS_USE_PROTO_PLUS (true by default)

Quickstart (local)

uv sync --extra dev
cp .env.example .env
# Fill .env with real credentials
uv run flin-google-keyword-planner-mcp

Claude integration

Option A: Published package (uvx)

{
  "mcpServers": {
    "flin-google-keyword-planner-mcp": {
      "command": "uvx",
      "args": ["flin-google-keyword-planner-mcp@latest"],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "REPLACE_ME",
        "GOOGLE_ADS_CLIENT_ID": "REPLACE_ME",
        "GOOGLE_ADS_CLIENT_SECRET": "REPLACE_ME",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_USE_PROTO_PLUS": "true"
      }
    }
  }
}

Option B: Local development checkout

{
  "mcpServers": {
    "flin-google-keyword-planner-mcp-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABSOLUTE/PATH/TO/flin-google-keyword-planner-mcp",
        "flin-google-keyword-planner-mcp"
      ],
      "env": {
        "GOOGLE_ADS_DEVELOPER_TOKEN": "REPLACE_ME",
        "GOOGLE_ADS_CLIENT_ID": "REPLACE_ME",
        "GOOGLE_ADS_CLIENT_SECRET": "REPLACE_ME",
        "GOOGLE_ADS_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "1234567890",
        "GOOGLE_ADS_USE_PROTO_PLUS": "true"
      }
    }
  }
}

Restart Claude Desktop after config changes.

Generate the refresh token in Claude

After Claude has loaded the MCP, ask it to run:

  1. google_ads_start_local_oauth_flow

  2. Open the returned authorization_url in your browser and approve Google Ads access.

  3. After the browser shows the local completion page, run google_ads_oauth_status.

  4. Run the keyword tools once token_available is true.

The default redirect URI is http://localhost:8080/. If your Google OAuth client uses a different loopback redirect URI, pass it to google_ads_start_local_oauth_flow.

If you cannot use the local callback flow, use the manual fallback:

  1. Run google_ads_authorization_url.

  2. Open the returned URL and approve access.

  3. Copy either the full redirected URL or the code query parameter.

  4. Run google_ads_exchange_authorization_code with that value.

The exchanged refresh token is stored outside Claude config in ~/.config/flin-google-keyword-planner-mcp/oauth-token.json and reused after MCP restarts. Override the storage path with FLIN_GOOGLE_ADS_TOKEN_FILE if needed.

Security

  • Never commit real credentials to git.

  • .env and .env.* are gitignored; only .env.example is tracked.

  • Keep secrets in environment variables or secret managers.

  • Rotate credentials immediately if accidentally exposed.

  • CI and release workflows run secret scanning with OSS gitleaks (no GITLEAKS_LICENSE secret required).

Testing

uv sync --extra dev
python3 -m pytest
python3 -m compileall src
uv build

Release automation (GitHub + PyPI)

  • CI workflow: .github/workflows/ci.yml

  • Release workflow: .github/workflows/release.yml

  • Tag push (v*) triggers:

  1. tests + compile + build + twine check

  2. publish to PyPI via Trusted Publishing (OIDC)

  3. GitHub Release creation with built artifacts

PyPI Trusted Publishing (one-time)

In the PyPI project flin-google-keyword-planner-mcp, add a Trusted Publisher:

  • Owner: flin-agency

  • Repository: flin-google-keyword-planner-mcp

  • Workflow: release.yml

  • Environment: pypi

Release steps

# 1) bump version in pyproject.toml + src/flin_google_ads_mcp/__init__.py
# 2) run checks
python3 -m pytest
python3 -m compileall src
uv build

# 3) release
git add -A
git commit -m "release: vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags

Available Tools

9 tools
keyword_ideas_from_keyword_and_urlC

Generate keyword ideas using KeywordAndUrlSeed.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
limitNo
networkNoGOOGLE_SEARCH_AND_PARTNERS
keywordsYes
page_tokenNo
customer_idNo
language_idNo1000
location_idsNo
login_customer_idNo
keyword_annotationNo
aggregate_metric_typesNo
include_adult_keywordsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility for behavioral disclosure. It fails to mention side effects, pagination behavior, rate limits, or authentication needs. The output schema exists but the description adds no behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, but it is under-specified for a tool with 12 parameters. Conciseness should not sacrifice completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high complexity (12 params, 0% schema coverage, no annotations, similar siblings), the description is severely incomplete. It lacks guidance on parameter usage, behavioral traits, and differentiation, making it inadequate for correct agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does not explain any parameter, not even the required keywords and url, offering no semantic value beyond the schema's minimal names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Generate keyword ideas using KeywordAndUrlSeed' clearly states the verb (generate) and resource (keyword ideas), and the seed type is implied by the tool name. However, it does not differentiate from sibling tools like 'keyword_ideas_from_keywords' which uses only keywords, missing a chance to clarify the unique combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context where this seed type is preferred, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

keyword_ideas_from_keywordsC

Generate keyword ideas using KeywordSeed.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
networkNoGOOGLE_SEARCH_AND_PARTNERS
keywordsYes
page_tokenNo
customer_idNo
language_idNo1000
location_idsNo
login_customer_idNo
keyword_annotationNo
aggregate_metric_typesNo
include_adult_keywordsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior, but it only says 'Generate keyword ideas using KeywordSeed.' It does not reveal safety traits, prerequisites, or side effects. For a tool with 11 parameters, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short at one sentence, which is concise but lacks structural elements like front-loading key info. It is under-specified for a tool with many parameters and sibling tools.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, a rich schema with 11 parameters, and existing output schema, the description is incomplete. It does not explain the impact of parameters like location, language, or network on results, nor does it clarify what the output contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the input schema provides no parameter descriptions. The description adds no meaning for any of the 11 parameters, so it fails to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Generate keyword ideas using KeywordSeed' which indicates the tool generates keyword ideas from keywords, but it lacks a specific verb and resource distinction. It does not differentiate from sibling tools that also generate keyword ideas from other inputs like URLs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not specify when to use this tool over alternatives like keyword_ideas_from_url or keyword_ideas_from_site, leaving the agent without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

keyword_ideas_from_siteC

Generate keyword ideas using SiteSeed.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
networkNoGOOGLE_SEARCH_AND_PARTNERS
site_urlYes
page_tokenNo
customer_idNo
language_idNo1000
location_idsNo
login_customer_idNo
keyword_annotationNo
aggregate_metric_typesNo
include_adult_keywordsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description only states it generates ideas without revealing behavioral traits such as read-only nature, side effects, or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (one sentence) but lacks necessary detail, making it under-specified rather than concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 parameters, no parameter explanations, and no mention of the output schema (which exists), the description is far from complete for effective tool usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description does not explain any of the 11 parameters, leaving the agent without understanding of their purpose or usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies generating keyword ideas using SiteSeed, but it lacks clarity on what SiteSeed is and does not differentiate from sibling tools like keyword_ideas_from_keywords or keyword_ideas_from_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool over alternatives. The description does not mention when to use SiteSeed vs other keyword idea generation methods.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

keyword_ideas_from_urlC

Generate keyword ideas using UrlSeed.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
limitNo
networkNoGOOGLE_SEARCH_AND_PARTNERS
page_tokenNo
customer_idNo
language_idNo1000
location_idsNo
login_customer_idNo
keyword_annotationNo
aggregate_metric_typesNo
include_adult_keywordsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, and the description lacks any behavioral details such as whether the tool is read-only, requires authentication, has rate limits, or what side effects occur. The agent has no insight beyond 'generate'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise and front-loaded. However, it is too brief given the tool's complexity, sacrificing necessary information for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count (11), no schema descriptions, no annotations, and the existence of sibling tools, the description is severely incomplete. It fails to cover usage, parameter roles, or return values, leaving the agent with insufficient context to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate by explaining key parameters. It only implies the 'url' parameter via the tool's name and description, but ignores the other 10 parameters (e.g., customer_id, language_id, filters). This adds minimal semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('generate') and the output ('keyword ideas') and specifies the source ('UrlSeed'). However, it does not differentiate from sibling tools like 'keyword_ideas_from_keywords' or 'keyword_ideas_from_site', leaving ambiguity about when to use this URL-based variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the siblings (e.g., when a URL-only input is available). No usage context, prerequisites, or examples are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

keyword_ideas_historicalC

Generate keyword ideas with historical metrics options (year-month range).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
networkNoGOOGLE_SEARCH_AND_PARTNERS
end_yearYes
keywordsYes
end_monthYes
page_tokenNo
start_yearYes
customer_idNo
language_idNo1000
start_monthYes
location_idsNo
login_customer_idNo
keyword_annotationNo
include_average_cpcNo
aggregate_metric_typesNo
include_adult_keywordsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as read/write nature, rate limits, or authentication requirements, leaving significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one sentence), but this brevity comes at the cost of omitting necessary details for a complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (16 params, 5 required, many optional), the description is insufficient; it does not cover the breadth of functionality or parameter roles.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 16 parameters, the description only mentions the date-range concept, failing to explain the many other parameters (e.g., keywords, location, network).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates keyword ideas and specifies 'historical metrics options' with a date range, distinguishing it from siblings that focus on different sources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lacks guidance on when to use this tool over siblings, only hinting at historical data without explicit comparison or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.2.6
    • Addedgoogle_ads_authorization_url
    • Addedgoogle_ads_exchange_authorization_code
    • Addedgoogle_ads_oauth_status
    • Addedgoogle_ads_start_local_oauth_flow
  2. 5 tool updatesv0.2.3
    • First observedkeyword_ideas_from_keyword_and_url
    • First observedkeyword_ideas_from_keywords
    • First observedkeyword_ideas_from_site
    • First observedkeyword_ideas_from_url
    • First observedkeyword_ideas_historical
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 9 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: OAuth flow tools handle different stages (authorization URL, code exchange, status, local server), and keyword tools use distinct seed types (keyword+URL, keywords, site, URL, historical). No ambiguity between any pair.

Naming Consistency5/5

All tools follow a consistent snake_case pattern. OAuth tools use the prefix 'google_ads_' followed by a verb_noun describing the action (e.g., authorization_url, exchange_authorization_code). Keyword tools uniformly start with 'keyword_ideas_from_' and specify the seed type. This consistent structure helps agents predict naming.

Tool Count5/5

9 tools is well-scoped for a Google Ads Keyword Planner MCP. It covers authentication setup (4 tools) and keyword idea generation from multiple seed types (5 tools), without unnecessary duplication. The count feels appropriate for the domain.

Completeness5/5

The tool set covers the full OAuth lifecycle (authorization, exchange, status, local flow) and provides all common ways to generate keyword ideas: from keywords, URL, site, and historical data. There are no obvious gaps for the stated purpose of keyword planning.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • google-ads-kw-mcp

    YerayRodri
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that exposes Google Ads keyword search volumes to AI agents via the KeywordPlanIdeaService, offering a free alternative to paid keyword-volume APIs.
    1
    MIT

  • google-ads-write-mcp

    YerayRodri
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that exposes write operations on Google Ads, enabling management of campaigns, ad groups, keywords, RSA ads, sitelinks, images, Customer Match audiences, and recommendations.
    MIT

  • Google Ads Campaign MCP

    clientskatbi
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for managing Google Ads campaigns through the official Google Ads API, covering accounts, campaigns, budgets, keywords, search terms, and keyword ideas. It provides tools for both reading and mutating live ads data, such as pausing campaigns, updating budgets, and adding keywords.
    MIT

  • Google Ads MCP Server

    qmedia-by
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for Google Ads API that enables LLMs to search and query Google Ads accounts, retrieve resource metadata, and generate keyword ideas.
    Apache 2.0