pipiads-mcp-server

PipiAds MCP Server

MCP Server for PipiAds advertising intelligence API. Enables AI assistants like Claude, OpenClaw, Cursor, and other MCP-compatible tools to search and analyze ads, products, stores, and competitors across TikTok and Facebook.

Requires Node.js 20 or newer.

Tools

Ad Search

Tool	Description
search_ads	Search ad videos across TikTok & Facebook by keyword, region, platform, engagement, ad spend, delivery days
get_ad_detail	Get detailed info for a specific ad by video ID

Product Search

Tool	Description
search_products	Search e-commerce products advertised on TikTok/Facebook by keyword, price, category, region, ad metrics
get_product_detail	Get product detail including images, price, landing page, Shopify data

Meta Ad Library Products

Tool	Description
search_adlibrary_products	Search Meta Ad Library products by price, platform, ad status, active days
get_adlibrary_product_detail	Get Meta Ad Library product detail with store and advertiser info

TikTok Shop Products

Tool	Description
search_tiktok_products	Search TikTok Shop products by sales, GMV, price, trends, influencers
get_tiktok_product_detail	Get TikTok Shop product detail

TikTok Shop Stores

Tool	Description
search_tiktok_shops	Search TikTok Shop stores by sales, GMV, product count, influencers
get_tiktok_shop_detail	Get TikTok Shop store detail by ID

Advertisers & Stores

Tool	Description
search_advertisers	Search advertiser leaderboard by platform, region, ad metrics, monthly visits
get_advertiser_detail	Get advertiser detail — domain, ad count, products, region distribution
search_stores	Search store ranking list by platform, region, ad metrics, monthly visits
get_store_detail	Get store detail by 13-char store ID

Store Deep Analysis

Tool	Description
get_store_competition	Get store competition product options for analysis
get_store_data_analysis	Get store all-platform data analysis (TikTok, Facebook, Meta)
get_store_play_cost	Get store play cost / daily ad increment statistics
get_store_region_analysis	Get store regional ad distribution analysis
get_store_ad_copy_analysis	Get store TikTok ad copy analysis
get_store_ad_schedule	Get store ad campaign schedule
get_store_product_analysis	Get store product analysis
get_store_rank_data	Get store traffic ranking data
get_store_ad_trend	Get store Meta Ad Library ad trend analysis
get_store_delivery_analysis	Get store Meta Ad Library in-depth delivery analysis
get_store_longest_run_ads	Get store longest-running ad content from Meta Ad Library
get_store_most_used_ads	Get store most-used ad content from Meta Ad Library
get_store_fb_pages	Get store Facebook advertiser pages from Meta Ad Library

Meta Ad Library Ads

Tool	Description
search_lib_ads	Search Meta Ad Library ads by content, platform, status, cost, reach, active days
get_lib_ad_detail	Get Meta Ad Library ad detail by ID

Rankings

Tool	Description
get_product_ranking	Get ad product ranking list
get_new_product_ranking	Get new ad product ranking list
get_app_ranking	Get top apps ranking list
get_new_app_ranking	Get new apps ranking list
get_app_dev_ranking	Get top app developers ranking list

App Analysis

Tool	Description
search_apps	Search apps advertised on TikTok/Facebook by category, system, downloads, revenue
get_app_detail	Get app detail by ID
search_app_developers	Search app developers by app count, downloads, revenue
get_app_developer_detail	Get app developer detail by ID

Natural Traffic Videos

Tool	Description
search_natural_videos	Search TikTok Made Me Buy It / natural traffic videos by plays, likes, followers

Ad Monitoring

Tool	Description
search_fb_advertisers	Search Facebook advertisers by name (for creating monitor tasks)
create_monitor_task	Create Facebook advertiser or store/website monitoring tasks from a target list (max 50)
list_monitor_tasks	List all ad monitoring tasks with optional filters
get_monitor_task_detail	Get monitor task detail by task ID
cancel_monitor_task	Cancel an ad monitoring task
get_monitor_board	Get monitoring task overview dashboard
set_monitor_task_group	Assign a monitor task to a group
get_monitor_realtime_overview	Get real-time overview of a monitor task
get_monitor_daily_overview	Get daily overview of a monitor task
get_monitor_landing_pages_overview	Get landing pages overview for a monitor task
get_monitor_latest_products	Get latest ad products discovered by a monitor task
get_monitor_product_list	Get ad product list for a monitor task with filters
get_monitor_landing_page_list	Get landing page list for a monitor task
get_monitor_ad_count_stats	Get ad count statistics for a monitor task
get_monitor_deep_analysis	Get deep campaign analysis for a monitor task
get_monitor_most_used_copy	Get most-used ad copy for a monitor task
get_monitor_longest_run_copy	Get longest-running ad copy for a monitor task
get_monitor_ad_list	Get ad list for a monitor task with extensive filters
get_monitor_ad_detail	Get ad detail from a monitor task by ad ID
get_monitor_product_stats	Get active ad product statistics for a monitor task

Monitor Groups & Notifications

Tool	Description
create_monitor_group	Create a new monitor task group
list_monitor_groups	List all monitor task groups
update_monitor_group	Update a monitor group name
delete_monitor_group	Delete a monitor group
get_monitor_notifications	Get current notification settings
save_monitor_notifications	Save notification settings (email, instant alerts, reports)

AI Image Search

Tool	Description
ai_search_submit_image	Submit an image for AI-powered visual search (returns image_id)
ai_search_image_status	Check processing status of a submitted image search
ai_search_image_summary	Get result summary of an AI image search
ai_search_image_ads	Search ads similar to a submitted image
ai_search_image_products	Search products similar to a submitted image
ai_search_image_stores	Search stores/advertisers similar to a submitted image
ai_search_image_tiktok_products	Search TikTok Shop products similar to a submitted image
ai_search_image_tiktok_shops	Search TikTok shops similar to a submitted image

Get API Key

1. Sign up at pipiads.com
2. Purchase credits
3. Get your API key from the dashboard

Installation

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pipiads": {
      "command": "npx",
      "args": ["-y", "pipiads-mcp-server"],
      "env": {
        "PIPIADS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add pipiads -e PIPIADS_API_KEY=your-api-key-here -- npx -y pipiads-mcp-server

OpenClaw

Add to ~/.openclaw/openclaw.json:

{
  "mcpServers": {
    "pipiads": {
      "command": "npx",
      "args": ["-y", "pipiads-mcp-server"],
      "env": {
        "PIPIADS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart the gateway: openclaw restart

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pipiads": {
      "command": "npx",
      "args": ["-y", "pipiads-mcp-server"],
      "env": {
        "PIPIADS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pipiads": {
      "command": "npx",
      "args": ["-y", "pipiads-mcp-server"],
      "env": {
        "PIPIADS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP-compatible tools

The configuration pattern is the same for any MCP client:

• Command: npx
• Args: ["-y", "pipiads-mcp-server"]
• Environment: PIPIADS_API_KEY = your API key

Environment Variables

Variable	Required	Description
PIPIADS_API_KEY	Yes	Your PipiAds API key
PIPIADS_BASE_URL	No	API base URL (default: https://www.pipispy.com)
PIPIADS_TIMEOUT_MS	No	Upstream request timeout in milliseconds (default: 30000)

Requests stop on timeout or MCP cancellation. Calls are not automatically retried: a timed-out write or paid query may already have been processed upstream.

Tool Input and Output

Unknown fields, invalid enum values, inverted numeric/date ranges and invalid pagination are rejected before calling the API. Search tools retain their existing 50/100-result limits; previously unbounded pagination is now capped at 100. Use extend_keywords for ad text search, for example:

{
  "extend_keywords": [{ "type": 1, "keyword": "phone case" }],
  "aigc_type": "-1",
  "ad_state": 1,
  "page_size": 10
}

aigc_type is a string: "-1" = AI generated, "0" = non-AI, "1" = advertiser labelled, "2" = official AI. is_and combines keywords, exclude_word excludes keyword items, and after carries the complete pagination cursor (for sort: 999, use the last result's _score and video_id).

Monitoring uses the dedicated /open-api/v1/monitor/data gateway. Supply exactly one of facebook_page_id_list, facebook_page_url_list, facebook_public_page_number_list, or facebook_shop_url_list, with 1–50 targets. For example:

{ "facebook_page_id_list": ["614178972053891"] }

The old advertiser_id argument remains as a single-ID alias and is converted to facebook_page_id_list. advertiser_name and monitor_task_type are not creation parameters. Notification switches use 1 for enabled and 2 for disabled. Persistent monitoring covers Facebook advertisers and stores/websites; TikTok research uses search/detail tools.

For ai_search_submit_image, provide exactly one input:

• image_url: a public HTTP/HTTPS URL, sent to /v3/api/open/ai-search/image/submit/image-url.
• image_data: standard Base64 bytes or a data:image/...;base64,... URL. JPEG, PNG, GIF, BMP and WebP are supported, up to 10 MiB. The server decodes the image and uploads a multipart file through /open-api/v1/upload-file.

Submission returns an image ID string. Poll ai_search_image_status until SEARCH_COMPLETED before retrieving search results; stop on ANALYSIS_FAILURE or SEARCH_FAILURE.

Successful results retain the original JSON text in content and also expose it as structuredContent.data. Tools advertise read/write and destructive-operation annotations; these are client hints, not authorization enforcement.

Usage Examples

Once configured, just talk to your AI assistant naturally:

• "Search for trending TikTok ads about phone cases in the US"
• "Find Shopify products with over 100k ad views in the last 30 days"
• "Get details for ad video ID 1795208137186337"
• "Show me TikTok Shop products with rising sales trends in beauty category"
• "Look up the store detail for store ID c2d5b2547218a"
• "Search Meta Ad Library for active ads about skincare"
• "Find top app developers on TikTok"
• "Create a monitor task for a Facebook advertiser"
• "Search for products similar to this image"

Credits

Pricing depends on the endpoint:

• Paid list/search tools: typically 1 credit per result returned.
• Paid detail tools: typically 1 credit per request, with a three-day repeat-query exemption where supported.
• Monitor creation: 1 credit per successfully created task. Cancellation does not refund spent credits.
• Monitoring reads/settings and image submission: free according to the API documentation; image result searches follow their own endpoint pricing.

Development

git clone <repo-url>
cd pipiads-mcp-server
npm ci
npm test
npm run typecheck

Tests run MCP client/server exchanges against an in-process fake API; they never use live credentials or consume credits. They cover monitoring routes and payloads, image multipart serialization, input validation, upstream errors, timeouts and cancellation isolation. npm pack/npm publish rebuild dist through prepack.

Test with MCP Inspector:

PIPIADS_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

License

MIT