@vskstudio/takt-mcp

Model Context Protocol server for Takt — query your sites' privacy-friendly analytics from any MCP-aware AI agent (Claude Desktop, Claude Code, Cursor, …).

The server is a thin, read-only client over the Takt public API. It runs on your machine and talks to a Takt instance using your API key — by default the hosted origin https://taktlytics.com, or your own self-hosted instance via TAKT_BASE_URL.

┌─────────────┐   stdio (MCP)   ┌────────────┐   HTTPS + Bearer   ┌──────────────┐
│  AI agent   │ ───────────────▶│  takt-mcp  │ ──────────────────▶│ Takt instance│
│ (Claude, …) │ ◀────────────── │ (this pkg) │ ◀───── JSON ────── │  /api/v1     │
└─────────────┘                 └────────────┘                    └──────────────┘

• Requirements

• Quick start

• Configuration

• Tools

• Resources

• How it works

• Troubleshooting

• Development

• Documentation

Requirements

• Node.js ≥ 18

• A Takt account on the hosted service (https://taktlytics.com), or a self-hosted Takt instance (set TAKT_BASE_URL)

• A Takt API key (Dashboard → Settings → API keys) with the permissions for the tools you want to use:

  • stats:read — every reporting tool (summary, timeseries, breakdown, realtime, goals, funnels, revenue, event properties, property breakdown)

  • sites:read — list_sites

A Takt API key is bound to a single site. So list_sites returns just that one site, and the domain you pass to the other tools must be the key's own domain (any other domain returns "site not found"). To cover several sites, mint one key per site and run one server instance per key.

Related MCP server: plausible-whenever-mcp

Quick start

The server runs straight from npm with npx — nothing to install or build. Every client below boils down to the same command, npx -y @vskstudio/takt-mcp, plus your TAKT_BASE_URL / TAKT_API_KEY in the environment.

Claude Code

One command, no file to edit (use -s user for a global install instead of the current project):

claude mcp add takt \
  -e TAKT_BASE_URL=https://taktlytics.com \
  -e TAKT_API_KEY=takt_sk_… \
  -e TAKT_ORG=my-org \
  -- npx -y @vskstudio/takt-mcp

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "takt": {
      "command": "npx",
      "args": ["-y", "@vskstudio/takt-mcp"],
      "env": {
        "TAKT_BASE_URL": "https://taktlytics.com",
        "TAKT_API_KEY": "takt_sk_…",
        "TAKT_ORG": "my-org"
      }
    }
  }
}

Codex CLI

Add a block to ~/.codex/config.toml:

[mcp_servers.takt]
command = "npx"
args = ["-y", "@vskstudio/takt-mcp"]
env = { TAKT_BASE_URL = "https://taktlytics.com", TAKT_API_KEY = "takt_sk_…", TAKT_ORG = "my-org" }

Cursor / Windsurf

Use the same mcpServers JSON as Claude Desktop, in ~/.cursor/mcp.json (Cursor) or ~/.codeium/windsurf/mcp_config.json (Windsurf).

VS Code (Copilot / Cline)

code --add-mcp '{"name":"takt","command":"npx","args":["-y","@vskstudio/takt-mcp"],"env":{"TAKT_BASE_URL":"https://taktlytics.com","TAKT_API_KEY":"takt_sk_…","TAKT_ORG":"my-org"}}'

Or commit a .mcp.json (Cline) / .vscode/mcp.json (Copilot, under a "servers" key) with the same fields.

Any other MCP client

The package ships a takt-mcp binary speaking MCP over stdio, so any client that can launch a command works:

TAKT_BASE_URL=https://taktlytics.com TAKT_API_KEY=takt_sk_… npx -y @vskstudio/takt-mcp

Useful flags:

npx @vskstudio/takt-mcp --version   # print the version
npx @vskstudio/takt-mcp --help      # print usage and the full environment reference

Configuration

The server is configured entirely through environment variables:

Invalid values fail fast at startup with a clear message on stderr.

Tools

Most tools accept a time filter:

• period — one of day, 7d, 30d, month, 6mo, 12mo (default 7d),

• or an explicit from/to range (YYYY-MM-DD),

• plus an optional tz (IANA timezone, e.g. Europe/Paris).

get_summary and get_timeseries also accept compareToPrevious to return the previous period of equal length. get_breakdown accepts dimension, an optional country (ISO-3166 alpha-2), and limit.

See the Tools reference for the full parameter list of each tool.

Resources

When TAKT_ORG is set, the server exposes one MCP resource:

How it works

• stdio transport. stdout carries the MCP protocol; all diagnostics go to stderr.

• Resilient HTTP. Each request has a timeout (TAKT_TIMEOUT_MS) and retries transient 429/5xx/network errors with exponential backoff and jitter, honouring Retry-After.

• Clean errors. Non-2xx responses are normalised to a Takt API error (status code): message, including the 402 quota_api_depasse billing case.

• Safe by construction. The base URL is validated; org/domain inputs are URL-encoded so they can't inject path segments; the API key never appears in any output.

See docs/architecture.md for the module layout and design rationale.

Troubleshooting

Set TAKT_DEBUG=1 to see each request (method, path, query) and retry decisions on stderr.

Development

pnpm install
pnpm test         # vitest
pnpm typecheck    # tsc --noEmit
pnpm lint         # eslint
pnpm build        # tsup → dist/

The full gate (what CI runs): pnpm lint && pnpm typecheck && pnpm test && pnpm build. See CONTRIBUTING.md.

Documentation

• Tools reference — every tool and parameter

• Configuration — env vars and tuning

• Architecture — modules and design

• Recipes — example prompts and flows

• Project wiki

License

MIT © VSK Studio