@datadive-tools/mcp

An MCP 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.
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:

{
  "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

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:

{
  "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 nicheIds 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). Paged by keyword: walk currentPage while hasNext is true, pageSize up to 100. | | 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. | | 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. | | 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

Six tools cannot be undone, so they require an explicit confirm: true argument. Called without it, they change nothing and return a note asking the assistant to confirm the cost with you first:

• create_niche_dive, redive_niche — spend dive tokens (scales with numberOfCompetitors).
• create_rank_radar — spends Search Term tokens (scales with numberOfKeywords).
• generate_listing_copy — spends one AI Copywriter prompt per call.
• delete_niche, delete_rank_radar — destroy data permanently.

Check your remaining balance any time with get_quota.

create_rank_radar uses that first, unconfirmed call to preview the creation against the API, so the note it comes back with can tell you something specific rather than only the token cost — for instance that the product family you asked for is already tracked by another of your Rank Radars, which would spend Tracked Search Terms on it twice. The preview creates nothing and spends nothing, and a warning never blocks the creation: two Rank Radars on one family is how you track two different sets of search terms and keep separate statistics.

The other write tools — pause_rank_radar, resume_rank_radar and the three *_rank_radar_search_terms tools — need no confirmation. They only move Daily Tracked Keywords capacity, which is freed again when you pause, and each is undone by its counterpart.

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

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 every confirm: true tool run without it — dives, rank radar creation, listing copy and the two deletes. |

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. | | Quota exceeded / … quota exceeded | The subscription's quota for that billable feature (Dive tokens, Rank Radar tracked keywords, AI Copywriter prompts, …) is used up. The message names the feature, the usage, the next refresh date when there is one, and links to the subscription overview page where it can be raised. Don't retry until it has been. | | 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 50). | | 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.tools with your API key as the x-api-key header.
• Your API key is stored only in your MCP client's config file (which you control). It is never sent anywhere else.
• The server logs nothing on its own. Standard backend access logs at DataDive record per-request metadata (organization, route, status, latency) the same way any direct API call would.

Development

npm install
npm run build       # tsup -> dist/index.js (with shebang)
npm test            # vitest run
npm run typecheck   # tsc --noEmit
npm run lint        # eslint

Test the binary end-to-end with the MCP Inspector:

DATADIVE_API_KEY=YOUR_API_KEY npx @modelcontextprotocol/inspector dist/index.js

Releasing

The repo uses Changesets:

npx changeset             # add a changeset describing the change (patch/minor/major)
git commit -am "fix: ..."
git push

A "Version Packages" PR opens automatically. Merging it bumps the version, updates CHANGELOG.md, and publishes to npm with provenance.

Support

• Issues: https://github.com/Data-Dive-Tools/datadive-mcp/issues
• API docs: https://developer.datadive.tools/docs#/v1
• DataDive support: [email protected]

License

MIT — see LICENSE.