datadive-mcp

# @datadive-tools/mcp

An [MCP](https://modelcontextprotocol.io) server that lets Claude (or any
MCP-compatible client) query your DataDive niches, keywords, competitors, and
Rank Radar data using your existing API key.

Runs locally on your machine over stdio. Your API key never leaves your machine
except as the `x-api-key` header on requests to `api.datadive.tools`.

## What you can ask

- "List my DataDive niches in marketplace `com`."
- "What's the master keyword list for niche `z515cGOFg3`?"
- "Who are the top competitors in niche X and what are their sales?"
- "What's my ranking juice for niche X — where can I improve?"
- "Show me my rank radars."
- "Plot the organic ranking trend for rank radar Y from 2024-03-01 to 2024-04-01."
- "Run a niche dive on ASIN B08N5WRWNW in the US marketplace with 5 competitors."
- "Refresh niche X with today's data, same competitors."
- "Re-dive niche X with 12 competitors but keep B08N5WRWNW in the set."
- "Is my dive done yet?"
- "Start a rank radar tracking 10 keywords for ASIN B08N5WRWNW in niche X."
- "Which Amazon seller accounts are connected?"
- "Search my catalog for active 'widget' products in the US."
- "What price or content changes happened on my listings last week?"

## 1. Get a DataDive API key

1. Sign in at [https://2.datadive.tools](https://2.datadive.tools/sign-in).
2. Go to **Settings → API Key** (`/api-key`).
3. Click **Generate API Key**. Copy the value — you'll paste it into your MCP
   client config below.

> Requires the **Billing Manager** or **Owner** role and the **Standard plan
> or higher**. Contact your org admin if you can't see the page.

## 2. Add it to your MCP client

### Claude Desktop

Edit your config file:

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

Add the `datadive` entry under `mcpServers`:

```json
{
  "mcpServers": {
    "datadive": {
      "command": "npx",
      "args": ["-y", "@datadive-tools/mcp"],
      "env": {
        "DATADIVE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Restart Claude Desktop. You should see `datadive` in the tools menu.

### Claude Code

```sh
claude mcp add datadive -- npx -y @datadive-tools/mcp
# Then add the env var via:
#   claude mcp add datadive --env DATADIVE_API_KEY=YOUR_API_KEY -- npx -y @datadive-tools/mcp
```

Or edit `.mcp.json` in your project / `~/.claude/mcp.json` globally with the
same JSON shape as above.

### Cursor

**Settings → MCP → Add new MCP server** and paste the same JSON shape:

```json
{
  "datadive": {
    "command": "npx",
    "args": ["-y", "@datadive-tools/mcp"],
    "env": { "DATADIVE_API_KEY": "YOUR_API_KEY" }
  }
}
```

## 3. Verify

Ask Claude: **"List my DataDive niches."**

You should see a tool call to `list_niches` and a JSON response with your
niches, plus pagination metadata. If you don't, see Troubleshooting below.

## Available tools

| Tool | Description |
|---|---|
| `list_niches` | Paginated list of your niches. Discovery step — returns `nicheId`s for the niche-scoped tools below. |
| `get_niche_keywords` | Master keyword list for a niche: search volume, relevancy, competitor ASIN ranks. |
| `get_niche_roots` | Keyword lexical roots for a niche — high-impact words with frequency and broad search volume. |
| `get_niche_competitors` | Competitor ASINs, titles, BSR, category and niche statistics (sales, revenue, ratings, opportunity score). |
| `get_ranking_juice` | DataDive proprietary ranking-juice metric per competitor (current vs optimized listing). |
| `list_rank_radars` | Paginated list of rank radars. Filter by `nicheId`, `searchText` or `status` (`ACTIVE` by default, plus `PAUSED`, `ARCHIVED`, `ALL`). |
| `get_rank_radar_data` | Historical keyword rankings for a rank radar within a `startDate`/`endDate` range (max 90 days). Returns every active keyword by default; pass `currentPage`/`pageSize` (up to 100) to read one page at a time. |
| `get_rank_radar_sqp_data` | Amazon Search Query Performance per Rank Radar keyword: search volume, impressions, clicks, cart adds, purchases — market total vs this ASIN family. Same date range and paging as `get_rank_radar_data`. |
| `get_rank_radar_ppc_data` | Sponsored Products metrics per Rank Radar keyword: sponsored rank, spend, sales, ACOS, CPC, match types; optional per-campaign breakdown. Same date range and paging as `get_rank_radar_data`. |
| `create_niche_dive` | **Spends dive tokens.** Starts new niche research from a seed ASIN. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
| `create_niche_dive_from_competitors_list` | **Spends dive tokens.** Starts niche research from your own list of 2–200 competitor ASINs, with no automatic discovery. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
| `redive_niche` | **Spends dive tokens.** Refreshes an existing niche with current data — either the same competitors or a newly discovered set. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
| `add_niche_keywords` | Adds keywords to a niche's Master Keyword List (1–100 per call). Free on a niche dived in the last 24 hours. **On an older niche it re-dives the niche and spends dive tokens** — then it asks for `confirm: true` first. |
| `remove_niche_keywords` | Takes keywords back out of a niche's Master Keyword List: hand-added ones are deleted, ones from Outliers/Residue go back there, dive-found ones stay. Free. |
| `list_keyword_exclusions` | The keywords a niche hides from its Master Keyword List: exact entries with their search volume, phrase entries with how many keywords and how much search volume they hide. |
| `add_keyword_exclusions` | Hides keywords from a niche's Master Keyword List — `exact` (one keyword) or `phrase` (every keyword containing it), 1–100 entries per call. Free; undone by `remove_keyword_exclusions`. |
| `remove_keyword_exclusions` | Removes exact or phrase exclusions so the keywords they hid show again. Free. |
| `get_dive_status` | Poll a dive started by `create_niche_dive` or `redive_niche`: `in_progress`, `success` (carries the `nicheId`), or `error`. |
| `create_rank_radar` | **Spends Search Term tokens.** Starts tracking keyword rankings for an ASIN in a niche. Returns a `rankRadarId`. Requires `confirm: true`. |
| `add_rank_radar_search_terms` | Starts tracking extra keywords on an existing rank radar. Takes one Daily Tracked Keywords slot per new keyword; reversible with `pause_rank_radar_search_terms`. |
| `pause_rank_radar_search_terms` | Pauses individual keywords of a rank radar, keeping their history and freeing their tracking slots. Takes keyword ids from `get_rank_radar_data`. |
| `resume_rank_radar_search_terms` | Restarts tracking on paused keywords of a rank radar. Takes back one tracking slot each. |
| `pause_rank_radar` | Pauses a whole rank radar (what the API calls archiving — listed under `status: PAUSED`, not `ARCHIVED`). Tracking stops, the history is kept, and the tracking slots are freed. Reversible with `resume_rank_radar`. |
| `resume_rank_radar` | Reactivates a paused rank radar, restoring as many keywords as the remaining quota allows (most relevant first). |
| `delete_rank_radar` | **Destroys ranking history.** Deletes a rank radar permanently (listed under `status: ARCHIVED`) and frees its tracking slots. Requires `confirm: true` — prefer `pause_rank_radar` if the data may be wanted later. |
| `delete_niche` | **Destroys niche data.** Deletes a niche with its keywords, competitors and dive history; spent dive tokens are not refunded. Blocked while a rank radar uses the niche. Requires `confirm: true`. |
| `generate_listing_copy` | **Spends an AI Copywriter prompt.** Drafts an optimised title, bullets and description from a niche's keyword research. Nothing is published to Amazon. Async — returns a `generationId`. Requires `confirm: true`. |
| `get_listing_copy_generation_status` | Poll a draft started by `generate_listing_copy`: `generating`, `complete` (carries the generated copy), or `failed`. Free to poll. |
| `list_seller_profiles` | Paginated list of connected Amazon seller accounts. Discovery step — returns the `sellerId` + `marketplace` the seller-scoped tools below (and the alert tools) need. |
| `get_seller_catalog` | Paginated catalog of a seller's own ASINs. Filter by `search`, `brand`, and `status` (Active by default). |
| `get_seller_listing_changes` | Paginated price/content/image changes on a seller's listings. Filter by `types`, `asin`, `brand`, `search`, and a date range; optionally include ranking/conversion `correlation`. |
| `list_ppc_campaigns` | Sponsored Products campaigns of a seller account with window totals and a per-placement breakdown. Filter by `asin` / `parentAsin`, `state`, `search`; sort by any metric. Window up to 90 days (default 30). |
| `get_asin_inventory_distribution` | Per-fulfillment-center sellable inventory for an ASIN. Requires `sellerId` from `list_seller_profiles` or your Connections page. |
| `list_indexing_issue_alerts` | Paginated list of indexing-issue alerts — ASINs no longer indexed for their tracked keywords. Filter by `sellerId`, `marketplace`, `status`, or `updatedSince`. |
| `list_blind_spend_alerts` | Paginated list of blind-spend alerts — ad spend on search terms with little or no sales, with per-term spend/clicks/CVR. Same filters as above. |
| `get_quota` | Current quota usage and capacity per billable feature, plus the next refresh date. No arguments. |
| `list_usage` | Paginated billable usage logs (token-consumption events). Filter by `type`, `search` (user), and `startDate`/`endDate`. |

All data is scoped to the organization that owns the API key. Most tools are
read-only. The tools that change something are marked above; the ones that
cannot be undone also require an explicit `confirm: true` — see
[Tools that change something](#tools-that-change-something).

### Tools that change something