Naver Searchad MCP

🚀 @packative/naver-searchad-mcp

An MCP (Model Context Protocol) server for the Naver SearchAd API. It allows you to manage campaigns, ad groups, ads, keywords, and retrieve performance statistics directly from Claude Desktop or any MCP-compatible client.

🚀 Quick Start

The @packative/naver-searchad-mcp is an MCP server for the Naver SearchAd API. You can manage various aspects of Naver SearchAd and retrieve performance statistics.

✨ Features

• 47 Tools covering the full Naver SearchAd API
• Campaign Management: List, get, create, update, and delete campaigns
• Ad Group Management: Full CRUD for ad groups
• Ad/Creative Management: List, get, create, update, and delete ads
• Keyword Management: Full CRUD for keywords
• Negative Keywords: Manage negative keywords at campaign or ad group level
• Ad Extensions: Manage sitelinks, callouts, and other ad extensions
• Keyword Tool: Get keyword suggestions, search volume, and bid estimates
• Performance Statistics: Detailed stats with flexible date ranges, breakdowns, and async reports
• Bizmoney/Budget: Check account balance, transaction history, and cost breakdowns
• Labels: Organize campaigns, ad groups, and other entities
• Business Channels: List and inspect business channels
• Account & Quality: Member info, keyword quality index, IP exclusions
• Permission Modes: --ro, --rw, --rwd flags to control access (read-only by default)
• TypeScript: Fully typed with modular architecture

📦 Installation

You can install the package using npm or pnpm:

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

Or with pnpm:

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

📚 Documentation

Configuration

Environment Variables

The server requires the following environment variables:

Permission Modes

The server supports three permission modes to protect against accidental destructive operations. The default is read-only.

Pass the flag as a CLI argument:

# Read-only (default, safest)
naver-searchad-mcp

# Allow creating and updating
naver-searchad-mcp --rw

# Full access including deletes
naver-searchad-mcp --rwd

If a tool is called that isn't allowed by the current permission mode, the server returns a clear error message indicating which mode is required.

Claude Desktop Setup

Add the following to your Claude Desktop configuration file: 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 Setup

Add to your Claude Code settings:

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

Available Tools (47)

Campaign Tools

Ad Group Tools

Ad (Creative) Tools

Keyword Tools

Negative Keyword Tools

Ad Extension Tools

Statistics Tools

Available metrics: impCnt (impressions), clkCnt (clicks), salesAmt (cost), ctr (CTR), cpc (CPC), ccnt (conversions), crto (conversion rate), convAmt (conversion value), ror (ROAS), cpConv (cost per conversion), avgRnk (avg rank)

Date presets: today, yesterday, last7days, last30days, lastweek, lastmonth, lastquarter

Breakdowns: pcMblTp (device), dayw (day of week), hh24 (hour), regnNo (region)

Keyword Research & Bid Estimate Tools

Bizmoney (Budget) Tools

Business Channel Tools

Label Tools

Other Tools

💻 Usage Examples

Basic Usage

List all campaigns

"Show me all my Naver SearchAd campaigns"

Get campaign performance

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

Create a new campaign

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

Keyword research

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

Check account balance

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

Get keyword statistics

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

Getting API Credentials

1. Log in to Naver SearchAd
2. Go to Tools > API Management
3. Create a new API key
4. Note your API Key, Secret Key, and Customer ID

For detailed API documentation, see the Official Naver SearchAd API Documentation.

🔧 Technical Details

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Type check
pnpm typecheck

# Build
pnpm build

Project Structure

src/
  index.ts                  # Server setup, permission mode, tool registration
  types/
    common.ts               # Shared types (ToolDefinition, AccessLevel, PermissionMode)
    campaigns.ts            # Campaign types
    adgroups.ts             # Ad group types
    keywords.ts             # Keyword types
    ads.ts                  # Ad/creative types
    stats.ts                # Stats & report types
    channels.ts             # Channel types
    bizmoney.ts             # Bizmoney types
    keyword-tool.ts         # Keyword suggestion & estimate types
    ad-extensions.ts        # Ad extension types
    negative-keywords.ts    # Negative keyword types
    labels.ts               # Label types
    misc.ts                 # Member, quality index, IP exclusion types
  tools/
    campaigns.ts            # Campaign tool definitions & handlers
    adgroups.ts             # Ad group tools
    keywords.ts             # Keyword tools
    ads.ts                  # Ad/creative tools
    stats.ts                # Stats & report tools
    channels.ts             # Channel tools
    bizmoney.ts             # Bizmoney tools
    keyword-tool.ts         # Keyword research & bid estimate tools
    ad-extensions.ts        # Ad extension tools
    negative-keywords.ts    # Negative keyword tools
    labels.ts               # Label tools
    misc.ts                 # Member, quality index, IP exclusion tools
  utils/
    fetchWithAuth.ts        # Authenticated HTTP client (HMAC-SHA256)

Requirements

• Node.js 18 or higher
• Naver SearchAd API credentials

📄 License

MIT License - see LICENSE for details.

Contributing

We use Conventional Commits for automatic versioning and changelog generation.

• development branch for ongoing work
• master branch is protected - merging triggers automatic releases

See CONTRIBUTING.md for detailed guidelines.

Issues and pull requests are welcome on GitHub.

About Packative

Packative is a Korean packaging e-commerce platform that helps businesses find and order custom packaging solutions. We build tools to streamline our marketing operations and share them with the community.

This MCP server is part of our marketing automation toolkit, enabling AI-assisted management of Naver SearchAd campaigns.