NicheHunter Partner MCP

A Model Context Protocol (MCP) server that wraps the NicheHunter Partner API. Lets Claude Desktop, Cursor, Cline, Continue, and any other MCP-compatible AI client query NicheHunter ad data via natural language tool calls.

Tools exposed

| Tool | Description | |------|-------------| | search_tiktok_shop_products | Filter TikTok Shop products by price, sales, rating, intelligence scores, etc. | | get_tiktok_shop_product | Fetch a single TikTok Shop product by ID | | search_tiktok_ads | Filter TikTok creative ads by keyword, country, niche, engagement, dates | | get_tiktok_ad | Fetch a single TikTok ad by ID | | search_facebook_ads | Search Facebook Ads Library with EU+UK demographics + scaling analytics | | get_facebook_ad | Fetch a single Facebook ad by archive ID | | search_pinterest_ads | Search Pinterest ads with CDN-hosted images | | get_pinterest_ad | Fetch a single Pinterest ad by ID |

Prerequisites

You need a Partner API account. If you don't have one yet, get in touch — you'll be issued a client_id, client_secret, and api_key.

Setup

Option 1: Run via npx (recommended once published)

Add this to your MCP client config. Examples below.

Option 2: Local install

git clone https://github.com/NH-TECHNOLOGIES/NicheHunter-Partner-API.git
cd NicheHunter-Partner-API/mcp-server
npm install
npm run build

Then point your MCP client at the absolute path of dist/index.js.

Client configurations

Claude Desktop

Edit your config file:

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

{
  "mcpServers": {
    "nichehunter": {
      "command": "node",
      "args": ["/absolute/path/to/NicheHunter-Partner-API/mcp-server/dist/index.js"],
      "env": {
        "NH_CLIENT_ID": "your_client_id",
        "NH_CLIENT_SECRET": "your_client_secret",
        "NH_API_KEY": "your_api_key"
      }
    }
  }
}

Restart Claude Desktop. You should see a hammer icon (tools available) in the chat input. Try: "Find the top 5 trending TikTok Shop products with over 100k sales sorted by opportunity score."

Cursor

Settings → MCP → Add new MCP Server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nichehunter": {
      "command": "node",
      "args": ["/absolute/path/to/NicheHunter-Partner-API/mcp-server/dist/index.js"],
      "env": {
        "NH_CLIENT_ID": "your_client_id",
        "NH_CLIENT_SECRET": "your_client_secret",
        "NH_API_KEY": "your_api_key"
      }
    }
  }
}

Cline (VS Code extension)

Open the Cline panel → MCP Servers → Edit MCP Settings:

{
  "mcpServers": {
    "nichehunter": {
      "command": "node",
      "args": ["/absolute/path/to/NicheHunter-Partner-API/mcp-server/dist/index.js"],
      "env": {
        "NH_CLIENT_ID": "your_client_id",
        "NH_CLIENT_SECRET": "your_client_secret",
        "NH_API_KEY": "your_api_key"
      },
      "alwaysAllow": []
    }
  }
}

Claude Code (CLI)

claude mcp add nichehunter -- node /absolute/path/to/dist/index.js \
  --env NH_CLIENT_ID=your_client_id \
  --env NH_CLIENT_SECRET=your_client_secret \
  --env NH_API_KEY=your_api_key

Environment variables

| Variable | Required | Default | Notes | |----------|----------|---------|-------| | NH_CLIENT_ID | yes | — | Cognito M2M client_id | | NH_CLIENT_SECRET | yes | — | Cognito M2M client_secret | | NH_API_KEY | yes | — | API Gateway x-api-key value | | NH_API_BASE | no | https://partner-api.nichehunter.com/v1 | Override for staging | | NH_TOKEN_URL | no | https://auth.nichehunter.com/oauth2/token | Override for staging | | NH_SCOPES | no | All 4 read scopes | Space-separated scope list |

Example prompts to try

• "Find Facebook ads scaling in the US with at least 50 active adsets, sorted by spend."
• "Get the top 10 trending TikTok Shop beauty products with rating above 4.5 and at least 10k sales."
• "Search Pinterest ads from Shopify stores in the UK with over 1000 saves."
• "Show me TikTok ads with high CTR (>2%) that have been running for at least 30 days."

The LLM will pick the right tool, fill in the filter arguments, call the API, and synthesise the results.

Verify it's working

After configuring, ask the LLM: "What tools do you have access to?" — it should list the 8 NicheHunter tools.

To debug, run the server directly and check stderr:

NH_CLIENT_ID=... NH_CLIENT_SECRET=... NH_API_KEY=... node dist/index.js

The server reads JSON-RPC messages from stdin and writes responses to stdout. Errors go to stderr (won't interfere with the protocol stream).

Rate limits

Tool calls are subject to your tier's rate limits. If you see errors like "API call failed (HTTP 429)", you've hit a quota or rate limit — wait and retry. See the trial tier limits in the welcome doc you received.

Troubleshooting

"Missing required environment variable: NH_CLIENT_ID" — your MCP client isn't passing env vars to the server process. Double-check the env block in your config file.

"Cognito token exchange failed (HTTP 401)" — credentials are wrong or the client doesn't exist anymore. Verify the values match what was issued.

"API call failed (HTTP 403): Missing required scope" — your NH_SCOPES doesn't include the scope the tool needs. Either remove NH_SCOPES (defaults to all 4) or include the missing one.

LLM doesn't see the tools — restart your MCP client after editing the config. Check the client's MCP logs for connection errors.