PPSPY MCP Server

MCP Server for PPSPY e-commerce intelligence API. Enables AI assistants like Claude, OpenClaw, Cursor, and other MCP-compatible tools to search and analyze Shopify stores, Facebook ads, ad monitoring, and sales tracking.

Tools

Shopify Stores

| Tool | Description | |------|-------------| | ppspy_shopify_store_list | Search and filter Shopify stores by region, language, revenue, traffic, theme, apps | | ppspy_shopify_store_details | Get detailed information for a specific Shopify store | | ppspy_shopify_store_traffic_list | Search Shopify stores with traffic data and source breakdown | | ppspy_shopify_single_product_store_list | Search single-product Shopify stores | | ppspy_shopify_theme_store_list | Search Shopify stores by theme |

Shopify Products

| Tool | Description | |------|-------------| | ppspy_shopify_product_list | Search and filter Shopify products by price, sales, category, revenue | | ppspy_shopify_bestselling_product_list | Get bestselling products for a specific Shopify store |

Ad Library - Ads

| Tool | Description | |------|-------------| | ppspy_advertisement_list | Search Facebook ads with advanced filters: keyword, audience reach, spend, platform, status | | ppspy_advertisement_details | Get detailed information for a specific advertisement |

Ad Library - Stores

| Tool | Description | |------|-------------| | ppspy_ad_store_list | Search ad library stores with advanced filters | | ppspy_ad_store_details | Get detailed information for a specific ad store | | ppspy_ad_store_landing_page_stats | Get landing page statistics for an ad store | | ppspy_ad_store_advertising_trends | Get advertising trends for an ad store over time | | ppspy_ad_store_placement_analysis | Get ad placement analysis (day of week and time period breakdown) | | ppspy_ad_store_content_most_used | Get most used ad copy content for a store | | ppspy_ad_store_content_longest_run | Get longest running ad content for a store | | ppspy_ad_store_advertiser_list | Get advertisers associated with a store |

Ad Library - Products

| Tool | Description | |------|-------------| | ppspy_ad_product_list | Search ad library products with advanced filters | | ppspy_ad_product_details | Get detailed information for a specific ad product |

Ad Monitoring

| Tool | Description | |------|-------------| | ppspy_ad_monitor_create_group | Create an ad monitoring group | | ppspy_ad_monitor_group_list | List all ad monitoring groups | | ppspy_ad_monitor_edit_group | Edit an ad monitoring group name | | ppspy_ad_monitor_delete_group | Delete an ad monitoring group | | ppspy_ad_monitor_advertiser_search | Search Facebook advertisers by name | | ppspy_ad_monitor_create_task | Create ad monitoring task(s) by advertiser ID, URL, page number, or shop URL | | ppspy_ad_monitor_task_list | List ad monitoring tasks with filters | | ppspy_ad_monitor_task_set_group | Assign a monitoring task to a group | | ppspy_ad_monitor_task_cancel | Cancel a monitoring task | | ppspy_ad_monitor_task_details | Get monitoring task details | | ppspy_ad_monitor_task_real_time_overview | Get real-time overview stats for a monitoring task | | ppspy_ad_monitor_task_daily_overview | Get daily overview for a monitoring task | | ppspy_ad_monitor_task_running_overview | Get aggregated dashboard stats for running tasks | | ppspy_ad_monitor_task_landing_page_overview | Get landing page overview for a monitoring task | | ppspy_ad_monitor_task_landing_page_list | Get landing page list with filters | | ppspy_ad_monitor_task_latest_ad_product | Get latest advertised products | | ppspy_ad_monitor_task_ad_product_overview | Get product overview by ad count | | ppspy_ad_monitor_task_ad_product_list | Get product list with filters | | ppspy_ad_monitor_task_ad_count_stats | Get ad count statistics over time | | ppspy_ad_monitor_task_ad_deep_analysis | Get ad placement analysis (by day of week or time period) | | ppspy_ad_monitor_task_ad_content_most_used | Get most used ad copy | | ppspy_ad_monitor_task_ad_content_longest_run | Get longest running ad content | | ppspy_ad_monitor_task_ad_list | Get ad list with extensive filters | | ppspy_ad_monitor_task_ad_details | Get detailed information for a specific monitored ad |

Sales Monitoring

| Tool | Description | |------|-------------| | ppspy_sales_monitor_create_group | Create a sales monitoring group | | ppspy_sales_monitor_group_list | List all sales monitoring groups | | ppspy_sales_monitor_edit_group | Edit a sales monitoring group name | | ppspy_sales_monitor_delete_group | Delete a sales monitoring group | | ppspy_sales_monitor_create_task | Create sales monitoring task(s) for store URLs (batch up to 50) | | ppspy_sales_monitor_task_list | List sales monitoring tasks with filters | | ppspy_sales_monitor_task_details | Get detailed sales monitoring task info including daily/hourly stats | | ppspy_sales_monitor_task_real_time_sales | Get real-time individual sales records | | ppspy_sales_monitor_task_update | Update sales monitoring task metadata (notes, group) | | ppspy_sales_monitor_task_stop | Stop a sales monitoring task | | ppspy_sales_monitor_task_delete | Delete stopped sales monitoring task(s) | | ppspy_sales_monitor_task_overview | Get aggregated sales overview (total, today, yesterday, 7-day) |

Supplement

| Tool | Description | |------|-------------| | ppspy_product_category_list | Get the list of product categories | | ppspy_ad_filter_options | Get ad filter options (button types and button texts) | | ppspy_shopify_theme_list | Get the list of Shopify themes |

Get API Key

1. Sign up at ppspy.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": {
    "ppspy": {
      "command": "npx",
      "args": ["-y", "ppspy-mcp-server"],
      "env": {
        "PPSPY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add ppspy -e PPSPY_API_KEY=your-api-key-here -- npx -y ppspy-mcp-server

OpenClaw

Add to ~/.openclaw/openclaw.json:

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

Restart the gateway: openclaw restart

Cursor

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

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

Windsurf

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

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

Other MCP-compatible tools

The configuration pattern is the same for any MCP client:

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

HTTP Mode

For web clients like OpenClaw gateway, you can also run in Streamable HTTP mode:

PPSPY_API_KEY=your-key npx ppspy-mcp-server --http
# Server runs at http://localhost:3000/mcp

Set a custom port with PORT environment variable.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PPSPY_API_KEY | Yes | Your PPSPY API key | | PORT | No | HTTP server port (default: 3000, only for --http mode) |

Usage Examples

Once configured, just talk to your AI assistant naturally:

• "Search for Shopify stores with the highest monthly revenue"
• "Find Facebook ads about pet products that have been running for over 30 days"
• "Show me the bestselling products for this Shopify store"
• "Get the ad trends for this store over the last 3 months"
• "Create an ad monitoring task for this Facebook advertiser"
• "What are the real-time sales for this store today?"
• "Search for ad products in the beauty category with high audience reach"
• "Show me the most used ad copy for this store"
• "List all my active sales monitoring tasks"

Credits

Each API call consumes credits from your PPSPY account:

• Shopify Store/Product Search: 1 credit per record
• Ad Library Search (Ads/Stores/Products): 2 credits per record
• Ad Monitoring / Sales Monitoring: 1 monitoring quota per task
• Detail/Analysis/Supplement APIs: Free

Development

git clone https://github.com/nicekid1/ppspy-mcp-server.git
cd ppspy-mcp-server
npm install
npm run build

Test with MCP Inspector:

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

License

MIT