Skip to main content
Glama
Sign In
Naver Search Ad MCP

Naver Search Ad MCP

by PlatAid
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Naver Search Ad MCP

An MCP server for the Naver Search Ad (네이버 검색광고) API — read/analytics focused. Query campaigns, ad groups, keywords, stats, keyword research, and bid estimates through any MCP client.

  • Read-only by default (safe): all tools are annotated readOnlyHint.

  • Multi-account: one credential per user auto-discovers every advertiser account it can access (agency-delegated + own) via /ad-accounts + child-ad-accounts, addressed by account_id (= Naver customerId).

  • Two transports: local stdio for a single account, or hosted streamable-http (Google Workspace OAuth) for a team — see DEPLOY.md.

Quick start (local, stdio)

Get your credentials at searchad.naver.com → 관리 → 도구 → API 사용 관리 (CUSTOMER_ID, access license, secret key).

uv venv --python 3.13
uv pip install -e .

export NAVER_API_KEY=...        # access license
export NAVER_SECRET_KEY=...     # secret key
export NAVER_CUSTOMER_ID=...    # customer id (integer)
naver-searchad-mcp             # stdio MCP server

Register with an MCP client (e.g. Claude Desktop):

{
  "mcpServers": {
    "naver-searchad": {
      "command": "/path/to/.venv/bin/naver-searchad-mcp",
      "env": {
        "NAVER_API_KEY": "...",
        "NAVER_SECRET_KEY": "...",
        "NAVER_CUSTOMER_ID": "..."
      }
    }
  }
}

Related MCP server: Google Ads MCP Server

Tools

Accounts

Tool

Description

list_accounts()

All accessible ad accounts (/ad-accounts ∪ child-ad-accounts, deduped). Each account_id = customerId

get_accounts_overview(...)

Per-account campaign count + period performance summary

whoami()

Diagnostic: authenticated caller + linked credential (hosted mode)

Entities

Tool

Description

list_campaigns(account_id, campaign_type?)

Campaigns

get_campaign(account_id, campaign_id)

Campaign detail

list_adgroups(account_id, campaign_id)

Ad groups

get_adgroup(account_id, adgroup_id)

Ad group detail

list_keywords(account_id, adgroup_id)

Keywords

list_ads(account_id, adgroup_id)

Ads (creatives)

list_business_channels(account_id)

Business channels

Performance & analytics

Tool

Description

get_stats(account_id, ids[], fields[], since/until|date_preset, ...)

Low-level /stats (≤92-day window, single entity level)

get_campaign_performance(account_id, dates, fields?)

All campaigns + names

get_keyword_performance(account_id, adgroup_id, dates)

Keyword performance + text

get_related_keywords(account_id, hint_keywords[])

Related keywords, search volume, competition (/keywordstool)

get_performance_report(account_id, level, since, until, daily?, ...)

Named report; auto-chunks >92 days; aggregate (ratios recomputed) or daily

create_stat_report(account_id, report_tp, stat_dt)

Async bulk StatReport job (1 job = 1 day)

download_stat_report(account_id, download_url, max_rows?)

Download StatReport TSV (raw, columns not interpreted)

Bid estimates

Tool

Description

estimate_keyword_bid(account_id, keywords[], estimate_type, device, position)

Target-position / min-exposure bid

estimate_keyword_performance(account_id, keyword, bids[], device)

Predicted impressions/clicks/cost per bid

Metric field names are terse and sometimes misleading (salesAmt = cost, ror = ROAS %); the server attaches clear aliases (cost, roas_pct, …) and exposes a naver://metric-glossary resource.

Hosted deployment (team, Google OAuth)

See DEPLOY.md — Cloud Run + Secret Manager + Google Workspace OAuth, per-email credential model, and a self-service admin console at /admin.

Development

uv pip install -e ".[dev]"
pytest

Notes

  • This server covers Search Ad only. Naver GFA (성과형 디스플레이광고) is a separate API (partner-only OAuth) and is out of scope.

  • Signing rule: base64(HMAC_SHA256(secret, "{timestamp}.{METHOD}.{path}")) — path only, query excluded, timestamp in ms.

License

MIT — see LICENSE.

Available Tools

19 tools
create_stat_reportA
Read-only

대량 StatReport 잡을 생성하고 완료까지 대기한다 (비동기, 1잡=1일).

반환의 downloadUrl을 download_stat_report로 받아 TSV를 얻는다. status가 NONE이면 해당 일자 데이터 없음.

Inputs: stat_dt (required), report_tp (required), account_id (required). Returns: object

download_stat_reportA
Read-only

StatReport TSV를 다운로드해 원본 행을 반환한다 (서명 필요).

⚠️ 컬럼 레이아웃은 reportTp별로 다르며 여기서 해석하지 않는다(위치 파싱 오매핑 방지). 각 reportTp의 컬럼 정의는 네이버 StatReport 스펙을 참조해 매핑하라. 명명형 지표가 필요하면 get_performance_report를 사용.

Inputs: account_id (required), download_url (required), max_rows. Returns: object

estimate_keyword_bidA
Read-only

키워드 입찰가를 추정한다 (POST /estimate/{type}/keyword).

average-position-bid=목표 평균순위 도달 입찰가, exposure-minimum-bid=최소 노출가.

Inputs: keywords (required), account_id (required), device, position, +1 more. Returns: object

estimate_keyword_performanceB
Read-only

입찰가별 예상 노출/클릭/비용을 추정한다 (POST /estimate/performance/keyword).

네이버 스키마: 키워드 1개 + 입찰가 리스트를 top-level로 전송. 응답의 estimate는 각 입찰가에 대응하는 {bid, impressions, clicks, cost} 배열이다.

Inputs: bids (required), keyword (required), account_id (required), device. Returns: object

get_accounts_overviewA
Read-only

내가 접근 가능한 계정들의 현황 요약(계정별 캠페인 수 + 기간 성과 합계).

접근 불가/오류 계정은 error 필드로 표시된다.

Inputs: since, until, date_preset. Returns: result

get_adgroupA
Read-only

단일 광고그룹 상세 (GET /ncc/adgroups/{id}).

Inputs: account_id (required), adgroup_id (required). Returns: object

get_campaignA
Read-only

단일 캠페인 상세 (GET /ncc/campaigns/{id}).

Inputs: account_id (required), campaign_id (required). Returns: object

get_campaign_performanceA
Read-only

계정의 모든 캠페인 성과를 이름과 함께 반환한다.

캠페인 열거 → /stats 조회 → nccCampaignId로 이름 join. 대시보드성 요약용.

Inputs: account_id (required), since, until, fields, +2 more. Returns: result

get_keyword_performanceB
Read-only

한 광고그룹의 키워드별 성과를 키워드 텍스트와 함께 반환한다.

Inputs: account_id (required), adgroup_id (required), since, until, +2 more. Returns: result

get_performance_reportA
Read-only

기간 성과 리포트 (명명형). 92일 초과 기간은 자동 청킹.

레벨별 엔티티를 열거해 /stats로 조회하고 이름을 붙여 반환한다. 합계 모드는 가산 지표(노출/클릭/비용/전환)를 합산 후 비율(CTR/CPC/전환율/ROAS)을 재계산한다. 대량(전 계정 키워드·장기 히스토리)은 저수준 StatReports 툴 사용을 권장. metrics/annotate로 응답 필드를 좁히면 전송·직렬화 비용을 줄일 수 있다(선택).

Inputs: level (required), since (required), until (required), account_id (required), +5 more. Returns: result

get_related_keywordsA
Read-only

연관 키워드와 월간 검색량·경쟁도를 조회한다 (GET /keywordstool).

저검색량 값('< 10')은 {value, approx, raw} 형태로 정규화한다.

Inputs: account_id (required), hint_keywords (required), show_detail. Returns: result

get_statsA
Read-only

동기 /stats 성과 조회. 윈도우 ≤ 92일, 레벨 혼합 불가, 최근/소량용.

반환 행에는 원본 필드(salesAmt 등)와 함께 명확한 별칭(cost 등)을 함께 붙인다.

Inputs: ids (required), fields (required), account_id (required), since, +4 more. Returns: result

list_accountsA
Read-only

내가 접근 가능한 광고주 계정 전체 목록.

/ad-accounts(개인 접근, SA+GFA) 와 child-ad-accounts(대행 위임 로스터)를 customerId로 합쳐(dedupe) 반환한다. 각 항목:

  • account_id = 검색광고 customerId (다른 조회 툴에 그대로 사용)

  • platforms = ['SA'|'GFA'...] (검색광고/디스플레이. GFA만 있으면 검색광고 데이터는 빈 결과)

  • roles = ['MASTER'|'OWNER'...] (오너/마스터가 아닌 권한도 포함)

  • sources = ['ad-accounts'|'child-ad-accounts'] (어느 소스에서 나왔는지) 여기 나오는 모든 account_id는 이 자격증명으로 조회 가능하다.

Inputs: no named parameters. Returns: result

list_adgroupsA
Read-only

캠페인의 광고그룹 목록 (GET /ncc/adgroups?nccCampaignId=).

Inputs: account_id (required), campaign_id (required). Returns: result

list_adsA
Read-only

광고그룹의 광고(소재) 목록 (GET /ncc/ads?nccAdgroupId=).

Inputs: account_id (required), adgroup_id (required). Returns: result

list_business_channelsB
Read-only

비즈니스 채널 목록 (GET /ncc/channels).

Inputs: account_id (required). Returns: result

list_campaignsB
Read-only

계정의 캠페인 목록을 조회한다 (GET /ncc/campaigns).

Inputs: account_id, campaign_type. Returns: result

list_keywordsA
Read-only

광고그룹의 키워드 목록 (GET /ncc/keywords?nccAdgroupId=).

Inputs: account_id (required), adgroup_id (required). Returns: result

whoamiA
Read-only

진단용: 현재 인증된 호출자 email과 연결된 자격증명 유무를 확인한다.

OAuth 토큰에서 email이 제대로 추출되는지 점검용. email 추출이 안 되면 claim_keys를 보고 추출 규칙을 조정한다.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    A3.8/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. For example, create_stat_report and download_stat_report are sequential steps, and get_stats and get_performance_report serve different use cases (sync vs. named reports). No overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (create_, download_, estimate_, get_, list_). The only outlier is whoami, which is conventional for diagnostics. No mixing of styles.

    Tool Count5/5

    19 tools cover account overview, campaign/adgroup/keyword details, performance reports, keyword estimation, and diagnostic tools. The number feels appropriate for the apparent scope of a search advertising management API.

    Completeness2/5

    The tool set is heavily read-oriented with only create_stat_report for report generation. There are no tools to create, update, or delete campaigns, adgroups, or keywords, which are critical for full management. This leaves significant gaps.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Google Ads MCP Server

      MaxGhenis
      A
      license
      A
      quality
      F
      maintenance
      A read-write MCP server for managing Google Ads campaigns, ad groups, keywords, and ads via natural language.
      12
      2
      -
    • google-ads-mcp

      google-ads-mcpofficial

      googleads
      A
      license
      B
      quality
      A
      maintenance
      MCP server that provides tools and resources for interacting with Google Ads API, enabling search, metadata retrieval, and account management through natural language.
      7
      6,309 PyPI
      1,165
      Apache 2.0

    • yandex-mcp

      SvechaPVL
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Yandex Direct, Metrika, Wordstat, and Webmaster APIs, providing 132 tools to manage advertising campaigns, analytics, keyword research, and reporting through any MCP-compatible client.
      58
      MIT