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"

📚 详细文档

配置

环境变量

服务器需要以下环境变量： | 变量 | 描述 | |------|------| | NAVER_API_KEY | 你的Naver SearchAd API密钥 | | NAVER_SIGN_KEY | 用于签署请求的Naver SearchAd秘密密钥 | | NAVER_CUSTOMER_ID | 你的Naver广告客户ID |

权限模式

服务器支持三种权限模式，以防止意外的破坏性操作，默认模式为只读。 | 标志 | 模式 | 工具数量 | 描述 | |------|------|---------|------| | --ro | 只读 | 26 | 仅支持列出、获取、统计和下载操作（默认） | | --rw | 读写 | 39 | 增加创建和更新操作 | | --rwd | 读写删除 | 47 | 提供包括删除操作在内的完全访问权限 |

你可以通过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种）

广告系列工具

| 工具 | 权限 | 描述 | |------|------|------| | list_campaigns | 读取 | 列出所有广告系列 | | get_campaign | 读取 | 获取特定广告系列的详细信息 | | create_campaign | 写入 | 创建新的广告系列 | | update_campaign | 写入 | 更新广告系列（名称、预算、投放方式、暂停/启用） | | delete_campaign | 删除 | 删除广告系列 |

广告组工具

| 工具 | 权限 | 描述 | |------|------|------| | list_adgroups | 读取 | 列出广告组，可根据广告系列进行过滤 | | get_adgroup | 读取 | 获取特定广告组的详细信息 | | create_adgroup | 写入 | 在广告系列中创建新的广告组 | | update_adgroup | 写入 | 更新广告组（出价、预算、暂停/启用） | | delete_adgroup | 删除 | 删除广告组 |

广告（创意）工具

| 工具 | 权限 | 描述 | |------|------|------| | list_ads | 读取 | 列出广告组中的所有广告 | | get_ad | 读取 | 获取特定广告的详细信息 | | create_ad | 写入 | 在广告组中创建新的广告 | | update_ad | 写入 | 更新广告（创意内容、暂停/启用） | | delete_ad | 删除 | 删除广告 |

关键词工具

| 工具 | 权限 | 描述 | |------|------|------| | list_keywords | 读取 | 列出广告组中的所有关键词 | | get_keyword | 读取 | 获取特定关键词的详细信息 | | create_keyword | 写入 | 向广告组中添加关键词 | | update_keyword | 写入 | 更新关键词（出价金额、暂停/启用） | | delete_keyword | 删除 | 删除关键词 |

否定关键词工具

| 工具 | 权限 | 描述 | |------|------|------| | list_negative_keywords | 读取 | 列出广告组或广告系列的否定关键词 | | create_negative_keywords | 写入 | 添加否定关键词（精确匹配或短语匹配） | | delete_negative_keywords | 删除 | 根据ID删除否定关键词 |

广告扩展工具

| 工具 | 权限 | 描述 | |------|------|------| | list_ad_extensions | 读取 | 列出广告组的广告扩展 | | create_ad_extension | 写入 | 创建广告扩展（网站链接、号召性用语等） | | delete_ad_extension | 删除 | 删除广告扩展 |

统计工具

| 工具 | 权限 | 描述 | |------|------|------| | get_stats | 读取 | 获取性能统计数据（展示次数、点击次数、费用、转化次数等） | | get_campaign_stats | 读取 | 获取所有活跃广告系列的统计数据及广告系列详细信息 | | create_stat_report | 写入 | 创建异步统计报告任务 | | get_stat_report | 读取 | 检查异步报告任务的状态 | | download_stat_report | 读取 | 下载已完成的统计报告 |

可用指标：impCnt（展示次数）、clkCnt（点击次数）、salesAmt（费用）、ctr（点击率）、cpc（每次点击费用）、ccnt（转化次数）、crto（转化率）、convAmt（转化价值）、ror（广告支出回报率）、cpConv（每次转化成本）、avgRnk（平均排名）

日期预设：today（今天）、yesterday（昨天）、last7days（过去7天）、last30days（过去30天）、lastweek（上周）、lastmonth（上月）、lastquarter（上季度）

细分维度：pcMblTp（设备）、dayw（星期几）、hh24（小时）、regnNo（地区）

关键词研究与出价估算工具

| 工具 | 权限 | 描述 | |------|------|------| | get_keyword_suggestions | 读取 | 获取带有搜索量、点击率和竞争数据的关键词建议 | | get_estimate_performance | 读取 | 估算给定出价金额下的展示次数、点击次数和费用 | | get_estimate_median_bid | 读取 | 获取在首页展示的中位出价 |

业务资金（预算）工具

| 工具 | 权限 | 描述 | |------|------|------| | get_bizmoney | 读取 | 获取当前账户余额 | | get_bizmoney_histories | 读取 | 获取交易历史（收费、退款） | | get_bizmoney_cost | 读取 | 获取按日期划分的费用明细 |

业务渠道工具

| 工具 | 权限 | 描述 | |------|------|------| | list_channels | 读取 | 列出所有业务渠道 | | get_channel | 读取 | 获取特定渠道的详细信息 |

标签工具

| 工具 | 权限 | 描述 | |------|------|------| | list_labels | 读取 | 列出所有标签 | | create_label | 写入 | 创建标签（名称 + 颜色） | | delete_label | 删除 | 删除标签 |

其他工具

| 工具 | 权限 | 描述 | |------|------|------| | get_member_info | 读取 | 获取账户/会员信息 | | get_quality_index | 读取 | 获取关键词质量得分和改进建议 | | list_ip_exclusions | 读取 | 列出为防止点击欺诈而阻止的IP地址 | | create_ip_exclusion | 写入 | 阻止一个IP地址 | | delete_ip_exclusion | 删除 | 解除对一个IP地址的阻止 |

开发

# 安装依赖
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广告系列。