Naver Searchad MCP

🚀 @packative/naver-searchad-mcp

這是一個適用於Naver SearchAd API的MCP（模型上下文協議）服務器。藉助它，你可以直接從Claude Desktop或任何支持MCP的客戶端管理廣告系列、廣告組、廣告、關鍵詞，並獲取性能統計數據。

🚀 快速開始

要使用此項目，你需要先獲取Naver SearchAd API的憑證，具體步驟如下：

1. 登錄 Naver SearchAd。
2. 進入“工具”>“API管理”。
3. 創建一個新的API密鑰。
4. 記錄下你的API密鑰、秘密密鑰和客戶ID。

詳細的API文檔可參考 Naver SearchAd官方API文檔。

✨ 主要特性

• 47種工具：全面覆蓋Naver SearchAd API。
• 廣告系列管理：支持列出、獲取、創建、更新和刪除廣告系列。
• 廣告組管理：提供廣告組的完整CRUD操作。
• 廣告/創意管理：可列出、獲取、創建、更新和刪除廣告。
• 關鍵詞管理：支持關鍵詞的完整CRUD操作。
• 否定關鍵詞管理：可在廣告系列或廣告組級別管理否定關鍵詞。
• 廣告擴展管理：支持管理網站鏈接、號召性用語等廣告擴展。
• 關鍵詞工具：可獲取關鍵詞建議、搜索量和出價估算。
• 性能統計：提供詳細的統計數據，支持靈活的日期範圍、細分和異步報告。
• 業務資金/預算：可查看賬戶餘額、交易歷史和費用明細。
• 標籤管理：用於組織廣告系列、廣告組和其他實體。
• 業務渠道管理：可列出和檢查業務渠道。
• 賬戶與質量：提供會員信息、關鍵詞質量指數和IP排除列表。
• 權限模式：支持--ro、--rw、--rwd標誌來控制訪問權限（默認只讀）。
• TypeScript支持：採用模塊化架構，提供完整的類型定義。

📦 安裝指南

你可以使用以下命令進行全局安裝：

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

或者使用pnpm：

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

💻 使用示例

基礎用法

列出所有廣告系列

"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"

📚 詳細文檔

配置

環境變量

服務器需要以下環境變量：

權限模式

服務器支持三種權限模式，以防止意外的破壞性操作，默認模式為只讀。

你可以通過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（點擊率）、cpc（每次點擊費用）、ccnt（轉化次數）、crto（轉化率）、convAmt（轉化價值）、ror（廣告支出回報率）、cpConv（每次轉化成本）、avgRnk（平均排名）

日期預設：today（今天）、yesterday（昨天）、last7days（過去7天）、last30days（過去30天）、lastweek（上週）、lastmonth（上月）、lastquarter（上季度）

細分維度：pcMblTp（設備）、dayw（星期幾）、hh24（小時）、regnNo（地區）

關鍵詞研究與出價估算工具

業務資金（預算）工具

業務渠道工具

標籤工具

其他工具

開發

# 安裝依賴
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             # 業務資金類型
    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             # 業務資金工具
    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 上提交問題和拉取請求。

關於Packative

Packative 是一個韓國包裝電子商務平臺，幫助企業尋找和訂購定製包裝解決方案。我們開發工具以簡化營銷操作，並與社區共享。

這個MCP服務器是我們營銷自動化工具包的一部分，支持通過AI輔助管理Naver SearchAd廣告系列。