@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 your Takt instance using your API key — no analytics data is exposed publicly, and nothing is hosted by us.

┌─────────────┐   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 self-hosted Takt instance
• 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.

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://takt.example.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://takt.example.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://takt.example.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://takt.example.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://takt.example.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:

Variable	Required	Default	Description
TAKT_BASE_URL	yes	—	Base URL of your Takt instance, e.g. https://takt.example.com. Must be http(s).
TAKT_API_KEY	yes	—	API key, sent as a Bearer token. Never logged.
TAKT_ORG	no	—	Default organization slug for list_sites and the takt://sites resource.
TAKT_TIMEOUT_MS	no	15000	Per-request timeout in ms (range 1000–120000).
TAKT_MAX_RETRIES	no	2	Retries on transient failures — 429/5xx/network (range 0–10).
TAKT_DEBUG	no	false	Set to 1/true to log diagnostics to stderr (the API key is never logged).

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

Tools

Tool	Description	Permission
list_sites	List the sites (domains) in an organization.	sites:read
get_summary	Top-line metrics: visitors, sessions, pageviews, bounce, duration.	stats:read
get_timeseries	Visitors/pageviews over time, bucketed by hour or day.	stats:read
get_breakdown	Top values of a dimension (pages, sources, countries, devices, …).	stats:read
get_realtime	Visitors active in the last 5 minutes.	stats:read
get_goals	Conversions per goal.	stats:read
get_funnels	Step-by-step funnel reports.	stats:read
get_revenue	Revenue grouped by currency for a revenue event.	stats:read
list_event_properties	List the custom property keys recorded for an event.	stats:read
get_property_breakdown	Break down a custom property of an event by value.	stats:read

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:

URI	Description
takt://sites	The sites in your organization, as JSON — context without a tool call.

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

Symptom	Likely cause / fix
TAKT_BASE_URL is required	The env var is unset or empty in your MCP client config.
TAKT_BASE_URL must use http:// or https://	Include the scheme, e.g. https://takt.example.com.
Takt API error (401 …)	The key is wrong or revoked.
Takt API error (403 …)	The key lacks the required permission (stats:read / sites:read).
site not found	The domain is not the key's site — keys are single-site bound.
Takt API error (402 quota_api_depasse)	The API quota for your plan is exhausted.
request timed out after …ms	Raise TAKT_TIMEOUT_MS, or check connectivity to your instance.

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