Keyword Research MCP

Keyword Research MCP는 Google Ads 키워드 플래닝 증거를 검색하고 정규화하는 경량 로컬 MCP 서버입니다. 현재 활발히 개발 중이며, 현재 저장소에는 실행 가능한 프로젝트 기반과 타입이 지정되고 테스트된 연구 인터페이스 및 프로덕션 Google Ads 어댑터가 포함되어 있습니다. 구현 계획에 설명된 MCP 도구 등록은 아직 구축 중입니다.

Google Ads의 유료 경쟁은 광고주의 활동을 설명합니다. 이 프로젝트는 이를 유기적 순위 난이도로 제시하지 않으며 복합 키워드 점수를 계산하지 않습니다.

요구 사항

• Python 3.10~3.14

• uv

테스트에는 Google Ads 자격 증명이 필요하지 않습니다. 프로덕션 어댑터가 Google Ads에 연결할 때 필요합니다.

Related MCP server: Google Ads MCP Server

Google Ads 구성

프로덕션 어댑터는 google-ads==31.2.0을 사용하며 Google Ads API v25를 명시적으로 선택합니다. 정확히 하나의 대상 고객과 하나의 인증 방법을 구성하세요. 고객 ID에는 하이픈이 포함될 수 있으며 메모리에서 정규화됩니다.

사용자 OAuth의 경우 다음을 설정하세요:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="987-654-3210" # optional manager account
export GOOGLE_ADS_CLIENT_ID="client-id-placeholder"
export GOOGLE_ADS_CLIENT_SECRET="client-secret-placeholder"
export GOOGLE_ADS_REFRESH_TOKEN="refresh-token-placeholder"

서비스 계정의 경우 세 가지 사용자 OAuth 설정을 생략하고 다음을 설정하세요:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/service-account.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="ads-user@example.test" # optional

또는 GOOGLE_ADS_CONFIGURATION_FILE_PATH를 로컬 google-ads.yaml을 가리키도록 설정하세요:

developer_token: developer-token-placeholder
customer_id: "123-456-7890"
login_customer_id: "987-654-3210"
client_id: client-id-placeholder
client_secret: client-secret-placeholder
refresh_token: refresh-token-placeholder

선택적 프로세스 설정은 KEYWORD_RESEARCH_CACHE_CAPACITY(기본값 128) 및 KEYWORD_RESEARCH_LOG_LEVEL(기본값 INFO)입니다. 자격 증명 파일, google-ads.yaml 및 .env 파일은 Git에서 무시됩니다.

설정 및 실행

uv sync
uv run keyword-research-mcp

이 명령은 stdio를 통해 실행되므로 MCP 클라이언트를 조용히 기다리며 프로토콜 메시지만 표준 출력에 씁니다.

개발

CI에서 사용하는 것과 동일한 품질 게이트를 실행하세요:

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv build

의도된 도구 계약, 아키텍처, 전달 단계 및 제품 경계는 구현 계획을 참조하세요.

라이선스

MIT