@trackdolphin/mcp

Ask your AI agent whether your shop's tracking is actually working — and get an answer from real numbers.

Trackdolphin is server-side conversion tracking for WooCommerce, Shopware, JTL-Shop, Shopify and custom frontends. This package is its Model Context Protocol server: it turns every available endpoint of the Trackdolphin API into an operation your agent can discover and call without loading hundreds of schemas at once.

• 📚 Docs: https://trackdolphin.com/en/docs/mcp
• 🌍 Website: https://trackdolphin.com
• 🧰 Command line: @trackdolphin/cli
• 📦 Browser & server SDK: @trackdolphin/sdk

Quick start

Add this to your MCP client configuration (Claude Desktop, Claude Code, Cursor, Windsurf, Zed, or anything else that speaks MCP over stdio):

{
  "mcpServers": {
    "trackdolphin": {
      "command": "npx",
      "args": ["-y", "@trackdolphin/[email protected]"],
      "env": { "TRACKDOLPHIN_TOKEN": "td_live_…" }
    }
  }
}

Create a personal key under Meine Einstellungen → Persönliche Schlüssel. It follows your current memberships across organisations. Organisation keys remain available for servers and integrations.

For local development, build this workspace with pnpm --filter @trackdolphin/mcp build, then use "command": "node" and "args": ["/absolute/path/to/apps/mcp/dist/index.js"].

Saving context (Kontext sparen)

Version 0.2.0 defaults to compact mode. The initial list contains three discovery tools, enable_toolset on stdio, and getAccessScope, listProjects, and searchEverything when the API and your access provide them:

| Tool | Purpose | | --- | --- | | search_tools | Search by query; optionally filter by exact tag or module. Returns names, one-line summaries, readOnly, required parameter names and modules. limit defaults to 5 (maximum 10); use nextOffset as offset for more matches. An empty query lists available toolsets. | | describe_tool | Supply name to retrieve its full description, input schema and annotations. | | call_tool | Supply name and an arguments object to execute that operation. | | enable_toolset | Supply module (for example ads) to expose its tools directly for this stdio session. enabled: false hides them again. |

For example, call search_tools with {"query":"keyword ausschließen","module":"ads","limit":3}, then describe_tool with {"name":"addNegativeKeywords"}. Fill in the required fields from that schema and pass them to call_tool as {"name":"addNegativeKeywords","arguments":{...}}. Search also accepts budget ändern, rechnungen, English terms and exact operation names.

Search is deterministic and offline after the startup OpenAPI fetch: weighted BM25 token matching over operation IDs, summaries, descriptions, tags and paths, with a small German/English vocabulary. It does not send searches to a model or external search service. Broad terms can return several related operations; check the description before choosing one.

Set TRACKDOLPHIN_MCP_TOOLSETS=ads,inbox,legal to expose these modules directly alongside discovery. Module names are normalized OpenAPI tags (Billing documents becomes billing-documents); Ad accounts and Ad changes share ads. Use an empty search to see this API's available names. Unknown or inaccessible configured toolsets expose nothing. Toolsets control visibility, never access.

For clients that manage large tool catalogs themselves, set TRACKDOLPHIN_MCP_TOOLS=all to expose all authorized API tools directly, as in 0.1.4. This mode omits discovery tools and ignores the toolset selection. To return to compact mode, unset the variable or set it to compact. Environment changes take effect on the next MCP server start. enable_toolset changes only the current stdio session and sends notifications/tools/list_changed; clients must refresh their tool list to see the change.

Backend responses above 12,000 characters become bounded JSON previews with truncated: true. When limit/offset are documented query parameters, the notice explains how to fetch a smaller page without skipping omitted rows. Otherwise use documented filters or a single-record operation. Do not repeat a mutation to recover its response. describe_tool deliberately returns the complete schema for the one operation requested. Search returns summaries instead of schemas.

Client configuration examples

Claude Code: put the Quick start JSON in your project's .mcp.json, or use:

claude mcp add --transport stdio \
  --env TRACKDOLPHIN_TOKEN=td_live_REPLACE_ME \
  --env TRACKDOLPHIN_MCP_TOOLSETS=ads,inbox \
  trackdolphin -- npx -y @trackdolphin/[email protected]

Claude Desktop: use the Quick start JSON in claude_desktop_config.json. Cursor: use it in .cursor/mcp.json. For either client, optional direct modules belong in the same env object:

"env": {
  "TRACKDOLPHIN_TOKEN": "td_live_REPLACE_ME",
  "TRACKDOLPHIN_MCP_TOOLS": "compact",
  "TRACKDOLPHIN_MCP_TOOLSETS": "ads,inbox,legal"
}

Restart or reconnect the client after changing its configuration. Updating the backend alone does not update an already installed or running npm server.

ChatGPT and remote MCP hosts: these need a reachable Streamable HTTP server instead of a local npx command. This repository includes src/http.ts, started with pnpm --filter @trackdolphin/mcp start:http. Configure discovery variables on that server. For a host supporting custom bearer headers, a connection configuration can look like this (the exact host format varies):

{
  "mcpServers": {
    "trackdolphin": {
      "url": "https://YOUR-MCP-HOST/mcp",
      "headers": { "Authorization": "Bearer td_live_REPLACE_ME" }
    }
  }
}

In a ChatGPT connector setup, use that hosted /mcp URL and a supported authentication method. The current HTTP entrypoint accepts per-request bearer keys; it does not implement OAuth. Hosts requiring OAuth need an authentication gateway that forwards the appropriate key. These client UI/authentication flows were not verified offline. HTTP is stateless, so enable_toolset and runtime list-change notifications are unavailable there; use server environment variables.

Upgrading from 0.1.4: that npm release predates the OpenAPI-to-JSON-Schema exclusive-bound converter. Version 0.2.0 bundles it, fixing Claude Code's exclusiveMinimum must be number rejection of backfillProjectEvents and enrichProjectPurchaseValues. Listing, description and execution validation all use the converted schemas. Install 0.2.0 and restart the client.

What you can ask

Once connected, these are ordinary questions for your agent:

• "Is tracking healthy on meinshop.de?" → checks delivery to every connected ad platform and names what is broken.
• "How many purchases did we send to Google Ads last week, and what did Google accept?" → sent, accepted and rejected side by side.
• "Which channels convert best this month?"
• "Where does the funnel leak between add-to-cart and purchase?"
• "Start the historical import for this shop."

How it works

The server holds no hand-written tool list. On start it fetches the OpenAPI description of the Trackdolphin API and derives a catalog with hundreds of operations. Compact mode exposes discovery plus a few essentials; full mode exposes the complete authorized catalog.

That is the point of API-first: a new endpoint is a new tool the same day, with no second list to keep in sync and no chance of the two drifting apart.

Access: read or write

On start the server asks the API what its token may do (getAccessScope) and says so in its MCP instructions, in one sentence: "This access may read and write in organisation X", or "read only", or which shared projects are view-only. A read-only access does not see write tools at all. Tools that no API token can ever call (creating API keys, inviting team members, billing, the internal admin console) are left out, so the agent is never offered a button that always answers 403.

API tools carry MCP annotations derived from their HTTP method and explicit OpenAPI overrides: readOnlyHint for GET, destructiveHint for DELETE, idempotentHint for GET/PUT/PATCH/DELETE.

call_tool is conservatively marked as potentially destructive because its target varies. The target's read-only, human-session, capability and integration restrictions remain in force, as do backend approval workflows. Direct and wrapped calls share schema validation, authentication, request construction and retry behavior. Unknown top-level arguments are rejected, including fields reserved for human sessions. HTTP resolves the key's current access on each discovery or execution request; stdio loads it at startup and the backend still enforces current rights. A successful response alone does not prove an ad platform received a change: verify the resulting state independently.

Configuration

| Variable | Meaning | Default | | --- | --- | --- | | TRACKDOLPHIN_TOKEN | Personal key from Meine Einstellungen → Persönliche Schlüssel (or an organisation key). Required. | — | | TRACKDOLPHIN_URL | Point at another instance. | https://api.trackdolphin.com | | TRACKDOLPHIN_MCP_TOOLS | compact or all. | compact | | TRACKDOLPHIN_MCP_TOOLSETS | Comma-separated modules exposed directly in compact mode. | Empty |

For the repository's HTTP entrypoint, PORT defaults to 8788 and each request supplies its own bearer token instead of TRACKDOLPHIN_TOKEN.

Requirements

Node.js 22 or newer. The npm executable speaks stdio and needs a client on the other end. The repository also provides the HTTP entrypoint described above.

Changelog

0.2.0

• Compact discovery by default, optional direct toolsets and full mode.
• Deterministic local search; session toolset changes notify stdio clients.
• Shared converted schemas and guarded execution; bounded API response previews.
• Bundles the JSON Schema 2020-12 exclusive-bound fix missing from npm 0.1.4.
• See CHANGELOG.md for release and validation details.

0.1.4

• Input schemas are complete. 0.1.3 showed no body fields for any tool, so arrays and booleans reached the API as text (konten must be an array). Request bodies are now resolved through $ref, allOf, list items and nested objects; nullable becomes JSON Schema type: [..., "null"]. Checked against the production API: 66 of 67 tools with a body complete (the last, saveConsentBanner, is fixed in the API itself).
• Knows its access. instructions state whether the token may read or write, and where; read-only access hides write tools; tools that need a dashboard login or staff rights are no longer listed (needs an API that publishes getAccessScope and x-trackdolphin-requires; older APIs get the full list and an honest "access unknown").
• The server reports its real version instead of 0.1.0.

0.1.3

• Tools carry MCP annotations; auth endpoints are not offered as tools.

Support

Issues and pull requests: https://github.com/trackdolphin/mcp. This repository is a snapshot of the Trackdolphin monorepo; every commit names the revision it came from.

License: MIT.

Auf Deutsch

Der MCP-Server macht aus jedem Endpunkt der Trackdolphin-API ein Werkzeug für deinen Agenten. Damit lässt sich fragen „läuft das Tracking bei meinshop.de sauber?“, und die Antwort kommt aus echten Zahlen statt aus einer Vermutung.

Die Werkzeugliste wird nicht gepflegt, sondern beim Start aus der OpenAPI-Beschreibung abgeleitet: Ein neuer Endpunkt ist sofort ein neues Werkzeug. Den API-Schlüssel erzeugst du im Dashboard unter Einstellungen → API; er gilt für eine Organisation und alle ihre Shops.

Deutsche Dokumentation: https://trackdolphin.com/de/docs/mcp

Personal keys

Create a key in Meine Einstellungen → Persönliche Schlüssel. Keep Alle meine Organisationen to follow all your current and future memberships, or select organisations. Nur lesen blocks writes. Copy the key once; revoke it on the same page. Membership removals and role changes apply on the next API request. Organisation keys remain available for servers and integrations.

Claude Code (hosted transport):

claude mcp add --env TRACKDOLPHIN_TOKEN=YOUR_PERSONAL_KEY \
  --transport stdio --scope user trackdolphin -- npx -y @trackdolphin/mcp@latest

The hosted MCP domain is not provisioned. Use the published stdio package above, or host the HTTP transport yourself as described earlier. Call listOrganisations / getAccessScope, then pass organisation_id to org operations; projectId / project_id derives the owning or shared context. Keys never change your dashboard selection or gain dashboard-only permissions.

Browser/device OAuth is a follow-up: the MCP server currently accepts bearer keys, not OAuth tokens. A proper flow needs authorization-server metadata, PKCE, short-lived access tokens, rotating refresh tokens, explicit scope consent and revocation linked to the same live personal principal. Device login also needs expiring device codes and polling limits. No partial OAuth flow is shipped.