Naver Searchad MCP

🚀 @packative/naver-searchad-mcp

Naver SearchAd API用のMCP（Model Context Protocol）サーバーです。Claude DesktopやMCP互換のクライアントから直接、キャンペーン、広告グループ、広告、キーワードを管理し、パフォーマンス統計を取得できます。

🚀 クイックスタート

このサーバーを使用することで、Naver SearchAd APIを通じて様々な広告関連の操作を行うことができます。以下の手順に従ってセットアップしてください。

✨ 主な機能

• 47のツール：Naver SearchAd API全体を網羅します。
• キャンペーン管理：キャンペーンの一覧表示、取得、作成、更新、削除が可能です。
• 広告グループ管理：広告グループに対する完全なCRUD操作をサポートします。
• 広告/クリエイティブ管理：広告の一覧表示、取得、作成、更新、削除ができます。
• キーワード管理：キーワードに対する完全なCRUD操作をサポートします。
• ネガティブキーワード：キャンペーンまたは広告グループレベルでのネガティブキーワードの管理が可能です。
• 広告拡張機能：サイトリンク、コールアウトなどの広告拡張機能の管理をサポートします。
• キーワードツール：キーワードの提案、検索量、入札見積もりを取得できます。
• パフォーマンス統計：柔軟な日付範囲、内訳、非同期レポートを含む詳細な統計情報を取得できます。
• Bizmoney/予算：アカウント残高、取引履歴、費用内訳を確認できます。
• ラベル：キャンペーン、広告グループ、その他のエンティティを整理するためのラベル管理機能があります。
• ビジネスチャネル：ビジネスチャネルの一覧表示と詳細確認ができます。
• アカウントと品質：会員情報、キーワード品質指数、IP除外設定を管理できます。
• 権限モード：--ro、--rw、--rwdフラグでアクセスを制御できます（デフォルトは読み取り専用）。
• TypeScript：モジュール化されたアーキテクチャで完全に型付けされています。

📦 インストール

npmを使用する場合：

npm install -g @packative/naver-searchad-mcp

pnpmを使用する場合：

pnpm add -g @packative/naver-searchad-mcp

📚 ドキュメント

環境変数

サーバーは以下の環境変数が必要です。

権限モード

サーバーは誤った破壊的操作を防ぐために3つの権限モードをサポートしています。デフォルトは読み取り専用です。

フラグはCLI引数として渡します。

# 読み取り専用（デフォルト、最も安全）
naver-searchad-mcp

# 作成と更新を許可
naver-searchad-mcp --rw

# 削除を含む完全なアクセス
naver-searchad-mcp --rwd

現在の権限モードで許可されていないツールが呼び出された場合、サーバーは必要なモードを示す明確なエラーメッセージを返します。

Claude Desktopの設定

Claude Desktopの設定ファイルに以下を追加してください。 macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "naver-searchad": {
      "command": "npx",
      "args": ["-y", "@packative/naver-searchad-mcp", "--rw"],
      "env": {
        "NAVER_API_KEY": "your-api-key",
        "NAVER_SIGN_KEY": "your-secret-key",
        "NAVER_CUSTOMER_ID": "your-customer-id"
      }
    }
  }
}

Claude Codeの設定

Claude Codeの設定に以下を追加してください。

{
  "mcpServers": {
    "naver-searchad": {
      "command": "npx",
      "args": ["-y", "@packative/naver-searchad-mcp", "--rw"],
      "env": {
        "NAVER_API_KEY": "your-api-key",
        "NAVER_SIGN_KEY": "your-secret-key",
        "NAVER_CUSTOMER_ID": "your-customer-id"
      }
    }
  }
}

利用可能なツール（47）

キャンペーンツール

広告グループツール

広告（クリエイティブ）ツール

キーワードツール

ネガティブキーワードツール

広告拡張機能ツール

統計ツール

利用可能なメトリクス：impCnt（インプレッション）、clkCnt（クリック）、salesAmt（費用）、ctr（CTR）、cpc（CPC）、ccnt（コンバージョン）、crto（コンバージョン率）、convAmt（コンバージョン価値）、ror（ROAS）、cpConv（コンバージョン単価）、avgRnk（平均順位）

日付プリセット：today（今日）、yesterday（昨日）、last7days（過去7日間）、last30days（過去30日間）、lastweek（先週）、lastmonth（先月）、lastquarter（前四半期）

内訳：pcMblTp（デバイス）、dayw（曜日）、hh24（時間）、regnNo（地域）

キーワードリサーチと入札見積もりツール

Bizmoney（予算）ツール

ビジネスチャネルツール

ラベルツール

その他のツール

💻 使用例

すべてのキャンペーンを一覧表示

"Show me all my Naver SearchAd campaigns"

キャンペーンのパフォーマンスを取得

"What's the performance of my Naver campaigns for the last 30 days?"

新しいキャンペーンを作成

"Create a new Naver SearchAd campaign called 'Summer Sale' with type WEB_SITE"

キーワードリサーチ

"Find keyword suggestions for '패키지 디자인' with search volume data"

アカウント残高を確認

"What's my current Naver SearchAd budget balance?"

キーワードの統計を取得

"Show me the click-through rate for my keywords in the last week"

API資格情報の取得

1. Naver SearchAdにログインします。
2. ツール > API管理に移動します。
3. 新しいAPIキーを作成します。
4. APIキー、シークレットキー、顧客IDをメモします。

詳細なAPIドキュメントについては、公式Naver SearchAd APIドキュメントを参照してください。

開発

# 依存関係のインストール
pnpm install

# テストの実行
pnpm test

# ウォッチモードでテストを実行
pnpm test:watch

# カバレッジ付きでテストを実行
pnpm test:coverage

# 型チェック
pnpm typecheck

# ビルド
pnpm build

プロジェクト構造

src/
  index.ts                  # サーバーのセットアップ、権限モード、ツールの登録
  types/
    common.ts               # 共有型 (ToolDefinition, AccessLevel, PermissionMode)
    campaigns.ts            # キャンペーン型
    adgroups.ts             # 広告グループ型
    keywords.ts             # キーワード型
    ads.ts                  # 広告/クリエイティブ型
    stats.ts                # 統計とレポート型
    channels.ts             # チャネル型
    bizmoney.ts             # Bizmoney型
    keyword-tool.ts         # キーワード提案と見積もり型
    ad-extensions.ts        # 広告拡張機能型
    negative-keywords.ts    # ネガティブキーワード型
    labels.ts               # ラベル型
    misc.ts                 # 会員、品質指数、IP除外型
  tools/
    campaigns.ts            # キャンペーンツールの定義とハンドラー
    adgroups.ts             # 広告グループツール
    keywords.ts             # キーワードツール
    ads.ts                  # 広告/クリエイティブツール
    stats.ts                # 統計とレポートツール
    channels.ts             # チャネルツール
    bizmoney.ts             # Bizmoneyツール
    keyword-tool.ts         # キーワードリサーチと入札見積もりツール
    ad-extensions.ts        # 広告拡張機能ツール
    negative-keywords.ts    # ネガティブキーワードツール
    labels.ts               # ラベルツール
    misc.ts                 # 会員、品質指数、IP除外ツール
  utils/
    fetchWithAuth.ts        # 認証済みHTTPクライアント (HMAC-SHA256)

必要条件

• Node.js 18以上
• Naver SearchAd API資格情報

📄 ライセンス

MITライセンス - 詳細はLICENSEを参照してください。

コントリビュート

自動バージョン管理と変更履歴生成にはConventional Commitsを使用しています。

• development ブランチで進行中の作業を行います。
• master ブランチは保護されており、マージすると自動リリースがトリガーされます。

詳細なガイドラインについては、CONTRIBUTING.mdを参照してください。

GitHubでのIssueとプルリクエストは歓迎されます。

Packativeについて

Packativeは韓国の包装eコマースプラットフォームで、企業がカスタム包装ソリューションを見つけて注文するのを支援します。私たちはマーケティング運用を合理化するためのツールを開発し、コミュニティと共有しています。

このMCPサーバーは、Naver SearchAdキャンペーンのAI支援管理を可能にするマーケティング自動化ツールキットの一部です。