naver-ads-mcp
This is a read-only MCP server that lets AI clients query Naver Search Ads data through standardized tools.
List and get details for campaigns, ad groups, keywords, ads, and ad extensions
Retrieve ad group targeting settings (day/time, region, device, media)
Get related keyword suggestions with monthly search volume and competition
Fetch performance metrics (impressions, clicks, CTR, CPC, cost, conversions, etc.) with date ranges, presets, and breakdowns by PC/mobile, day, hour, or region
List business channels and linked customer accounts (agency use)
Call any arbitrary read-only API endpoint via a generic
naver_ads_getfallbackSwitch customer accounts per call using an optional
customerIdargumentAll tools are read-only; no create, update, or delete operations are exposed
Provides read-only access to the Naver Search Ads API, enabling querying of campaigns, ad groups, keywords, ads, ad extensions, business channels, customer links, and performance statistics.
naver-ads-mcp
네이버 검색광고 API를 감싼 stdio MCP 서버. 캠페인·광고그룹·키워드·소재 구조와 성과 지표를 MCP 클라이언트(Claude Code, Claude Desktop 등)에서 바로 조회합니다.
현재 범위는 조회 전용입니다. 생성·수정·삭제 툴은 아직 노출하지 않습니다.
요구 사항
Node.js 20 이상
네이버 검색광고 API 라이선스 — 광고시스템 > 도구 > API 사용 관리에서 발급 (무료)
Related MCP server: Kakao Keyword Ads MCP
빠른 시작
이 저장소에서 바로 받아 씁니다. 별도 설치 단계는 없고, MCP 클라이언트가 알아서 프로세스를 띄웁니다.
npx -y github:2duckchun/naver-ads-mcp --help특정 브랜치나 태그를 물리려면 #을 붙입니다.
npx -y github:2duckchun/naver-ads-mcp#v0.1.0 --help환경변수
MCP 클라이언트 설정의 env로 넘깁니다(아래 등록 예시 참고). 로컬에서 소스를 직접 돌릴 때는 .env.example을 복사해 씁니다.
변수 | 필수 | 기본값 | 설명 |
| ● | 액세스라이선스 | |
| ● | 비밀키 | |
| ● | 광고계정 ID (숫자) | |
|
| API 베이스 URL | |
|
| 요청 타임아웃 | |
|
| 429·5xx·네트워크 오류 재시도 횟수 |
값이 비었거나 형식이 틀리면 기동 시 어떤 변수가 문제인지 한 번에 stderr로 출력하고 종료합니다.
MCP 클라이언트 등록
Claude Code
claude mcp add naver-ads \
--env NAVER_SA_API_KEY=... \
--env NAVER_SA_SECRET_KEY=... \
--env NAVER_SA_CUSTOMER_ID=... \
-- npx -y github:2duckchun/naver-ads-mcpClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"naver-ads": {
"command": "npx",
"args": ["-y", "github:2duckchun/naver-ads-mcp"],
"env": {
"NAVER_SA_API_KEY": "...",
"NAVER_SA_SECRET_KEY": "...",
"NAVER_SA_CUSTOMER_ID": "..."
}
}
}
}로컬 클론을 직접 물리려면
command를node,args를["/절대경로/naver-ads-mcp/dist/index.js"]로 바꾸면 됩니다.
툴
모두 readOnlyHint가 붙은 조회 전용입니다. 각 툴은 customerId를 선택 인자로 받아 호출 단위로 광고계정을 바꿀 수 있습니다(대행사 계정용).
툴 | 엔드포인트 | 용도 |
|
| 캠페인 목록 |
|
| 캠페인 단건 |
|
| 광고그룹 목록 |
|
| 광고그룹 단건 |
|
| 요일·시간, 지역, 매체 타게팅 |
|
| 키워드 목록·입찰가 |
|
| 키워드 단건 |
|
| 연관 키워드·월간 검색량 |
|
| 광고 소재 목록 |
|
| 광고 소재 단건 |
|
| 확장 소재 |
|
| 성과 지표 |
|
| 비즈채널 |
|
| 연결된 광고계정 |
| (임의 GET) | 전용 툴이 없는 엔드포인트용 탈출구 |
get_stats는 ids에 nccCampaignId / nccAdgroupId / nccKeywordId / nccAdId를 섞어 받고, 기간은 since+until 또는 datePreset 중 하나로 지정합니다. 둘 다 생략하면 네이버 기본 기간이 적용됩니다. breakdown으로 PC/모바일·요일·시간대·지역별 분해가 가능합니다.
/stats는ids를 콤마 조인으로,fields를 JSON 배열로 받습니다. 한쪽 형식을 반대로 보내면 전체가 400입니다(ids→유효하지 않은 ID 형식입니다,fields→fields 파라미터 파싱 실패). 이 비대칭은src/tools/__tests__/stats.test.ts로 고정해 두었습니다.
인증 방식
네이버 검색광고 API는 요청마다 HMAC 서명을 요구합니다.
X-Timestamp: {epoch milliseconds}
X-API-KEY: {액세스라이선스}
X-Customer: {광고계정 ID}
X-Signature: base64(HMAC-SHA256(secretKey, "{timestamp}.{METHOD}.{path}"))서명 대상 경로에는 쿼리스트링이 들어가지 않습니다. /stats?ids=...를 호출해도 서명에는 /stats만 씁니다. 이 규칙은 src/naver/signature.ts에 격리되어 있고 단위 테스트로 고정되어 있습니다.
서버 시각이 네이버와 수 분 이상 어긋나면 403이 납니다.
구조
src/
├── index.ts 진입점 — 설정 로드, serveStdio, 시그널 처리
├── server.ts McpServer 조립
├── config.ts 환경변수 zod 검증
├── naver/
│ ├── signature.ts HMAC 서명 + 인증 헤더
│ ├── client.ts 서명된 HTTP 클라이언트 (쿼리 직렬화·재시도·타임아웃)
│ └── errors.ts NaverAdsApiError / NaverAdsTransportError
├── tools/
│ ├── define.ts registerReadTool — 조회 툴 등록 헬퍼
│ ├── shared.ts 공통 인자·enum
│ └── *.ts 도메인별 툴
└── utils/result.ts CallToolResult 직렬화툴 추가하기
registerReadTool이 읽기 힌트·JSON 직렬화·에러 변환을 처리하므로, 툴 파일에는 "무엇을 어떤 인자로 부르는가"만 남습니다.
registerReadTool(server, {
name: 'list_labels',
title: '라벨 목록 조회',
description: '광고계정에 등록된 라벨을 조회합니다. ...',
inputSchema: z.object({ customerId: customerIdArg }),
run: ({ customerId }) => client.get('/ncc/labels', undefined, { customerId }),
});src/tools/index.ts의 registerAllTools에 등록 함수를 추가하면 끝입니다.
에러 처리 방침
네이버 API 오류는 예외로 던지지 않고 isError: true 툴 결과로 내려보냅니다. 프로토콜 오류로 던지면 모델이 원인을 보지 못해 스스로 교정할 수 없기 때문입니다. 결과에는 status·code·title·detail과 문의용 transactionId, 그리고 상태 코드별 조치 힌트가 함께 들어갑니다.
stdout 규칙
stdout은 JSON-RPC 전용입니다. 로그는 반드시 stderr로 보내야 하며, Biome의 suspicious/noConsole 규칙을 error로 올려 실수를 막고 있습니다.
개발
git clone https://github.com/2duckchun/naver-ads-mcp.git
cd naver-ads-mcp
pnpm install
cp .env.example .env # 발급받은 키 입력pnpm dev # tsx로 직접 실행 (.env 있으면 자동 로드)
pnpm build # dist/ 재생성
pnpm test # vitest
pnpm lint # biome check (린트 + 포맷 + import 정렬)
pnpm lint:fix # 자동 수정
pnpm check # typecheck + lint + test
pnpm inspect # MCP Inspector로 툴 확인 (pnpm build 후)dist 는 저장소에 커밋됩니다
빌드 산출물 dist/ 를 추적하고, 설치 시점에 빌드하던 prepare 스크립트는 두지 않습니다.
설치 경로가 빌드 툴체인에 의존하지 않게 하려는 것입니다.
그래서 src/ 를 고쳤으면 pnpm build 후 dist/ 도 함께 커밋해야 합니다.
CI 가 pnpm build 를 돌린 뒤 git diff --exit-code -- dist 로 어긋남을 막습니다.
설치 경로별 동작
node 22 / npm 10.9.8 기준으로 확인했습니다.
방법 | 결과 |
| 정상 |
| 정상 |
| 정상 |
| 깨짐 — 아래 참고 |
npm install -g 에 git 주소를 직접 주면 npm 이 전역 node_modules 항목을 npm 캐시
안의 임시 클론 디렉터리(_cacache/tmp/git-clone*)로 심링크합니다. 그 디렉터리는 설치
직후 지워지므로 링크가 끊기고, 종료코드는 0인데 실행파일은 없는 상태가 됩니다.
이건 이 패키지에 국한된 문제가 아닙니다. 무관한 저장소(github:isaacs/rimraf)도 -g
로는 실패합니다(이쪽은 exit 127). npm 10.x 의 git 스펙 + -g 조합 문제로 보이며,
dist 를 커밋해도 이 경로는 살아나지 않습니다.
Docker 이미지에 넣는다면 tarball 경로를 쓰세요. dist 가 커밋되어 있으므로 클론에
빌드 툴체인이 필요 없고, 설치 후 클론을 지워도 실행파일이 남습니다.
RUN git clone --depth 1 --branch v0.1.0 \
https://github.com/2duckchun/naver-ads-mcp.git /src \
&& cd /src && npm install -g "$(npm pack | tail -1)" \
&& rm -rf /src알려진 제약
get_stats의timeIncrement: '1'(일별 추이)은/stats에서 "지원하지 않는 기능입니다"(400)로 거부될 수 있습니다. 일별 데이터는 대용량 리포트(/stat-reports) 쪽 기능입니다.get_stats의breakdown은 최근 7일 이내 기간에서만 동작합니다. 더 긴 기간과 함께 쓰면 400입니다.list_customer_links는 대행사(매니저) 계정 전용입니다. 일반 광고주 계정으로 부르면 본문 없는 404가 돌아옵니다.목록 조회 툴의 선택 파라미터는 확실한 것만 노출했습니다. 페이지네이션(
baseSearchId,recordSize)이나selector같은 파라미터가 필요하면naver_ads_get으로 우회하세요.응답은 타입 없이 그대로 통과시킵니다. 도메인 타입은 필요한 시점에 붙이는 편이 낫다고 판단했습니다.
다음 단계 후보
쓰기 툴 (
POST/PUT/DELETE) —NAVER_SA_ALLOW_WRITE같은 안전장치와 함께대용량 리포트 (
/stat-reports,/master-reports) — 잡 생성 → 폴링 → 다운로드입찰가 추정 (
/estimate/*)자주 쓰는 분석 절차를 MCP Prompt로 제공
참고
Available Tools
15 toolsget_ad광고 소재 단건 조회BRead-onlyIdempotent
nccAdId로 광고 소재 하나의 상세 정보를 조회합니다.
Inputs: adId (required), customerId.
get_adgroup광고그룹 단건 조회CRead-onlyIdempotent
nccAdgroupId로 광고그룹 하나의 상세 정보를 조회합니다.
Inputs: adgroupId (required), customerId.
get_adgroup_targets광고그룹 타게팅 조회BRead-onlyIdempotent
광고그룹에 설정된 타게팅(요일·시간, 지역, 매체, PC/모바일 등)을 조회합니다.
Inputs: adgroupId (required), customerId.
get_campaign캠페인 단건 조회BRead-onlyIdempotent
nccCampaignId로 캠페인 하나의 상세 정보를 조회합니다.
Inputs: campaignId (required), customerId.
get_keyword키워드 단건 조회BRead-onlyIdempotent
nccKeywordId로 키워드 하나의 상세 정보를 조회합니다.
Inputs: keywordId (required), customerId.
get_stats성과 지표 조회ARead-onlyIdempotent
캠페인·광고그룹·키워드·소재의 성과 지표를 조회합니다. ids는 종류를 가리지 않고 nccCampaignId / nccAdgroupId / nccKeywordId / nccAdId를 모두 받습니다. since+until과 datePreset 중 하나만 지정하세요. 둘 다 생략하면 네이버 기본 기간이 적용됩니다.
Inputs: ids (required), since, until, fields, +4 more.
list_ad_extensions확장 소재 목록 조회BRead-onlyIdempotent
캠페인 또는 광고그룹에 붙은 확장 소재(전화번호, 위치정보, 홍보문구 등)를 조회합니다.
Inputs: ownerId (required), customerId.
list_adgroups광고그룹 목록 조회ARead-onlyIdempotent
캠페인에 속한 광고그룹 목록을 조회합니다. 광고그룹은 입찰가·소재·키워드를 묶는 단위입니다. campaignId를 생략하면 광고계정 전체 광고그룹을 조회합니다.
Inputs: adgroupIds, campaignId, customerId.
list_ads광고 소재 목록 조회BRead-onlyIdempotent
광고그룹에 등록된 광고 소재(제목·설명·연결 URL)와 검수 상태를 조회합니다.
Inputs: adgroupId (required), customerId.
list_business_channels비즈채널 목록 조회ARead-onlyIdempotent
광고계정에 등록된 비즈채널(웹사이트, 전화번호, 네이버 톡톡, 쇼핑몰 등)을 조회합니다. 광고그룹이 연결하는 대상입니다.
Inputs: customerId.
list_campaigns캠페인 목록 조회ARead-onlyIdempotent
광고계정의 캠페인 목록을 조회합니다. 캠페인은 파워링크·쇼핑검색·파워컨텐츠 등 광고 유형과 예산을 관리하는 최상위 단위입니다. 반환되는 nccCampaignId는 list_adgroups의 입력값이 됩니다.
Inputs: customerId, campaignIds.
list_customer_links연결된 광고계정 조회BRead-onlyIdempotent
대행사·광고주 간 연결된 광고계정 목록을 조회합니다. 여기서 얻은 customerId를 다른 툴의 customerId 인자로 넘겨 여러 계정을 오갈 수 있습니다.
Inputs: type, customerId.
list_keywords키워드 목록 조회ARead-onlyIdempotent
광고그룹에 등록된 키워드 목록과 입찰가·상태를 조회합니다. 노출·클릭·비용 같은 성과 지표는 포함되지 않으므로 get_stats를 함께 쓰세요.
Inputs: adgroupId (required), customerId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Tools target distinct resources with clear list/get separation; only minor potential confusion between list_ads and list_ad_extensions, or the generic naver_ads_get fallback, but descriptions clarify intended use.
Predominantly list_/get_ + noun in snake_case; the generic naver_ads_get breaks the pattern and get_adgroup_targets uses get_ for what is a list operation, but overall readable and predictable.
15 tools is within the recommended range and each maps to a clear resource or operation; the generic fallback prevents over-proliferation for uncovered endpoints.
Surface is entirely read-only: no create, update, or delete operations for campaigns, adgroups, keywords, ads, or extensions; agents cannot perform ad management lifecycle tasks, a major gap for an ads platform.
Related MCP Connectors
Read-only MCP access to your DEXUN AdWhiz account: ad accounts, AI recommendations, savings.
Read-only MCP connector for Adlane workspaces, Google and Meta ad accounts and campaign reports.
Read your Amazon Ads campaigns, results, rules and activity, every marketplace and ad type.
Read-only Google Ads, GA4 and Search Console data for Claude, with no Google Cloud setup.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides read-only access to Google Ads account data including campaigns, ad groups, keywords, and performance reports. Enables querying via GAQL through an MCP interface.MIT
- AlicenseAqualityDmaintenanceEnables querying and analysis of Kakao Keyword Ads data, including campaigns, ad groups, keywords, and performance reports. Supports 21 read-only tools and 2 resources for accessing ad account information and metrics.25MIT
- AlicenseAqualityBmaintenanceA read-only MCP server for querying Google Ads data using GAQL, enabling AI assistants to safely read campaign performance, ad groups, and keywords.12527 PyPI1MIT
- AlicenseBqualityDmaintenanceRead-only MCP server for Google Ads API, enabling natural language queries about campaigns, metrics, search terms, and change history without write access.6MIT