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 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` or `status`. |
| `get_rank_radar_data` | Historical keyword rankings for a rank radar within a `startDate`/`endDate` range. |
| `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`. |
| `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`. |
| `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`. |
| `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`. |
| `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 three tools below spend tokens (`get_dive_status` only polls a
dive and is read-only) — see
[Creating dives & rank radars](#creating-dives--rank-radars).

### Creating dives & rank radars

`create_niche_dive`, `redive_niche` and `create_rank_radar` **consume billable
tokens and cannot be undone**, so they require an explicit `confirm: true`
argument. The assistant should confirm the cost with you before passing it. The
amount scales with `numberOfCompetitors` (dives and re-dives) /
`numberOfKeywords` (rank radars). Check remaining balance any time with
`get_quota`.

To skip the per-call confirmation (e.g. in an automated setup), set
`DATADIVE_AUTO_CONFIRM_WRITES=true` in your client config — then these tools run
without `confirm`.

None of the three is **safe to retry** — each call spends tokens again and
creates a separate dive / re-dive / Rank Radar, even with identical arguments. If
a call errors or times out, check `get_dive_status` / `list_niches` /
`list_rank_radars` for what already exists before calling again.

Dives are **asynchronous**. `create_niche_dive` returns a `diveId` and an
estimated completion time immediately; poll `get_dive_status` with that `diveId`
until it reports `success`, which carries the new `nicheId` you then feed to
`list_niches`, `get_niche_keywords`, and the other niche tools.

`redive_niche` refreshes a niche you already have rather than creating another
one, and it keeps the same `nicheId` — so rank radars and reports built on that
niche follow the refreshed data. It takes a `mode`:

- `same_competitors` — re-dive the niche's current competitor set. Nothing else
  to supply; use it purely to pull in current sales, price and keyword data.
- `discover` — search for a fresh competitor set of `numberOfCompetitors` ASINs.
  Steer it with `heroAsin` (the seed to build around; defaults to the niche's
  highest-selling competitor, preferring one of your own ASINs), `lockedAsins`
  (kept no matter what discovery finds) and `excludedAsins` (never selected).

> ⚠️ For `create_niche_dive`, `marketplace` uses full Amazon domain suffixes
> (`com`, `co.uk`, `com.mx`, `co.jp`, …) — e.g. the UK marketplace is `co.uk`,
> not `uk`.

## Configuration

| Env var | Required | Default | Notes |
|---|---|---|---|
| `DATADIVE_API_KEY` | yes | — | Generate at https://2.datadive.tools/api-key |
| `DATADIVE_API_BASE_URL` | no | `https://api.datadive.tools` | Override for staging |
| `DATADIVE_AUTO_CONFIRM_WRITES` | no | `false` | Set truthy to let `create_niche_dive` / `create_rank_radar` run without `confirm: true`. |

## Troubleshooting

If a tool call returns an error message, it'll be one of these — each maps to a
specific HTTP status from the DataDive API.

| Message starts with… | What to do |
|---|---|
| **Authentication failed: your DATADIVE_API_KEY is invalid or expired** | The key is wrong, deleted, or expired. Generate a new one at https://2.datadive.tools/api-key. |
| **Subscription is inactive or paused** | Resume billing at https://2.datadive.tools — the API key is valid but the subscription isn't active. |
| **Forbidden** | The key is valid but doesn't have access to that resource. Usually a niche/rank-radar that belongs to a different org. |
| **Rate limit exceeded** | Wait a few seconds and retry. |
| **Bad request** | Check the parameters — the message echoes the server's validation error (e.g., `pageSize must not exceed 100`). |
| **DataDive API error (5xx)** | Transient backend issue. Try again; if it persists, contact support. |
| **Network error reaching …** | Your machine can't reach `api.datadive.tools` — check VPN / firewall / DNS. |

If the server itself fails to start, look in your MCP client's log output:

- **`DATADIVE_API_KEY environment variable is required`** — the env var isn't
  being passed through to the binary. Confirm your client config has it under
  `env` (not `args`), and that you've restarted the client after editing.

## Privacy

- The MCP server runs locally on your machine. It is a thin shim — every tool
  call becomes a single HTTPS request from your machine to
  `api.datadive.