Naver Search Ad

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": "..."
      }
    }
  }
}

Tools

Accounts

Entities

Performance & analytics

Bid estimates

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.