etracker MCP Server

Streamable-HTTP MCP server for the etracker Analytics Report API. Read-only, 4 tools, runs in a container.

The REST Report API is available in the etracker analytics Enterprise Edition. Create an access token with scope Reporting API under Settings → Account → Integration.

Table of contents

• Run in Docker

• Authentication

• Connect from your client

  • Claude Code

  • Claude Desktop

  • Cursor

  • n8n

  • VS Code (Copilot Chat)

  • MCP Inspector (debug)

• Tools

• Example prompts

• Configuration

• Operations

• Development

Related MCP server: Akamai Traffic MCP

Run in Docker

Published image: ghcr.io/mittwald/etracker-mcp:latest (tags: latest, 0.1.0).

docker run -d --name etracker-mcp -p 3334:3334 \
  --restart unless-stopped \
  ghcr.io/mittwald/etracker-mcp:latest

The server is credential-free at startup — every client provides its own etracker access token via a header (see Authentication).

Endpoint: http://127.0.0.1:3334/mcp · Healthcheck: GET /health.

Build locally instead: docker build -t etracker-mcp . and use etracker-mcp as the image name.

docker compose

services:
  etracker-mcp:
    image: ghcr.io/mittwald/etracker-mcp:latest
    ports: ["3334:3334"]
    restart: unless-stopped

Authentication

Each client provides its own etracker access token via a request header:

• X-ET-Token — access token with scope Reporting API.

The server keeps no global credentials, holds nothing in env, and stores nothing on disk. The token lives only in the per-session EtrackerClient inside the running process. One server can serve many etracker accounts. Requests without the header are rejected with 401.

The upstream API base URL defaults to the public endpoint https://ws.etracker.com/api/v7 and can be overridden server-side with ETRACKER_API_URL.

Connect from your client

All client examples below include the required X-ET-Token header. Replace the token with your own.

Claude Code

claude mcp add etracker http://127.0.0.1:3334/mcp --transport http \
  --header "X-ET-Token: your-access-token"

Claude Desktop

Claude Desktop's stable config only accepts stdio MCP servers. To use this HTTP-based server, bridge it via the mcp-remote shim (auto-installed by npx). This also lets you pass the required X-ET-Token header, which the Connectors UI doesn't support.

Step-by-step:

1. Quit Claude Desktop (⌘Q on macOS · right-click tray → Quit on Win/Linux).

2. Open the config file:

   OS	Path
   macOS	~/Library/Application Support/Claude/claude_desktop_config.json
   Windows	%APPDATA%\Claude\claude_desktop_config.json
   Linux	~/.config/Claude/claude_desktop_config.json

3. Add (or merge into) mcpServers:

   {
     "mcpServers": {
       "etracker": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "http://127.0.0.1:3334/mcp",
           "--header",
           "X-ET-Token: your-access-token"
         ]
       }
     }
   }

4. Save the file and reopen Claude Desktop. The first launch downloads mcp-remote (one-time, ~5 s).

5. Open a new chat → type /mcp and press Enter. etracker should appear with status connected and 4 tools listed.

If it shows failed: check that the MCP server is running (curl http://127.0.0.1:3334/health → {"ok": true}) and that Node.js is installed system-wide (npx must be on your PATH).

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "etracker": {
      "url": "http://127.0.0.1:3334/mcp",
      "headers": {
        "X-ET-Token": "your-access-token"
      }
    }
  }
}

n8n

In an AI Agent workflow add the MCP Client Tool node:

• Endpoint: http://127.0.0.1:3334/mcp (or the container hostname if n8n runs in Docker, e.g. http://etracker-mcp:3334/mcp on the same network).

• Server Transport: HTTP Streamable.

• Headers: add X-ET-Token.

Connect the node to the tools input of the AI Agent. n8n introspects tools/list automatically, so the etracker tools become available to the agent without further config.

VS Code (Copilot Chat)

.vscode/mcp.json:

{
  "servers": {
    "etracker": {
      "type": "http",
      "url": "http://127.0.0.1:3334/mcp",
      "headers": {
        "X-ET-Token": "your-access-token"
      }
    }
  }
}

MCP Inspector (debug)

npx @modelcontextprotocol/inspector
# Streamable HTTP → http://127.0.0.1:3334/mcp
# Add the X-ET-Token header in the Inspector "Authentication" panel.

Tools

The etracker Report API is report-centric: pick a report (e.g. EAPage, EAGeo, EADeviceType), then query its rows. Each report exposes attributes (dimensions) and keyfigures (metrics).

A typical flow: list_reports → get_report_metadata (to learn valid attribute/figure IDs) → get_report_data (or compare_report_data for period-over-period analysis). compare_report_data defaults the comparison period to the equally long span immediately before the current range.

Example prompts

Marketing-oriented questions for the connected assistant:

• "Which reports are available in my etracker account?"

• "Show me the top 10 pages by unique visits in May 2024 (EAPage)."

• "Break down visits by device type for the last 7 days."

• "Which countries drove the most traffic last month? Sort descending."

• "List pages whose name matches "Checkout" with more than 100 unique visits."

• "Compare page impressions for /en/ vs /de/ URLs over the last 30 days."

Configuration

The etracker access token is not configured via env — it is passed by each client via the X-ET-Token request header. See Authentication.

Operations

• Logging: structured JSON to stdout/stderr (info/debug → stdout, warn/error → stderr). One line per event, no header values logged. Tail with docker logs -f etracker-mcp.

• Healthcheck: GET /health returns {"ok": true, "version": "..."}. Wired into the Dockerfile HEALTHCHECK.

• Limits: request bodies > 1 MB → 413; outbound calls to etracker timeout after 30 s. The etracker API itself limits to 50 calls per 5 minutes, 10 parallel requests, and 100,000 rows per response.

• Security model: server holds no credentials. Run multiple replicas behind a load balancer if needed — sessions are sticky via the Mcp-Session-Id header, so terminate sessions on the same backend (or accept that a reconnect re-initializes a session).

• Image: pin a digest in production (ghcr.io/mittwald/etracker-mcp@sha256:…) rather than :latest.

• Graceful shutdown: SIGTERM/SIGINT close all open MCP sessions and drain in-flight requests before exit (10 s hard cap).

Development

pnpm install
pnpm dev           # tsx watch
pnpm test          # unit tests
pnpm test:live     # live smoke test, needs ETRACKER_TOKEN env
pnpm build         # tsc → dist/

All tools are read-only. Add a tool: extend src/tools.ts, add a unit test in tests/tools.test.ts, add a live test in tests/live/live.test.ts that asserts the actual response shape.