TelemetryDeck

An MCP server that wraps the TelemetryDeck analytics API, allowing Claude to query app telemetry data and run analytics using TQL (TelemetryDeck Query Language).

Installation

Claude Code

claude mcp add telemetrydeck --transport http https://mcp-builder.de/telemetry/mcp

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "telemetrydeck": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/telemetry", "telemetry-deck-mcp"]
    }
  }
}

Install the bundled skill (optional)

This repo ships a Claude Code skill at skills/telemetrydeck/SKILL.md that wraps the MCP tools with a guided workflow: it offers to auto-install the TelemetryDeck MCP (and chrome-devtools MCP, if Google sign-in is needed), drives the login, and writes TQL queries from natural-language questions.

The skill is one self-contained file. To install it on your machine, fetch it directly:

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills\telemetrydeck" | Out-Null
Invoke-WebRequest -OutFile "$env:USERPROFILE\.claude\skills\telemetrydeck\SKILL.md" `
  https://raw.githubusercontent.com/faaak2/mcp-telemetry/main/skills/telemetrydeck/SKILL.md

# macOS / Linux
mkdir -p ~/.claude/skills/telemetrydeck
curl -o ~/.claude/skills/telemetrydeck/SKILL.md \
  https://raw.githubusercontent.com/faaak2/mcp-telemetry/main/skills/telemetrydeck/SKILL.md

Or if you have the repo cloned: cp skills/telemetrydeck/SKILL.md ~/.claude/skills/telemetrydeck/SKILL.md.

Restart Claude Code, then ask things like "show me yesterday's signups on Web Player" or "DAU on iOS this week" — the skill triggers and walks the rest of the setup.

Running the Server

Prerequisites

• Python >= 3.11
• uv

Install dependencies

uv sync

Start the server

uv run telemetry-deck-mcp

The server starts on http://0.0.0.0:8083 using streamable HTTP transport.

Run as a systemd service

A service file is included for running the server in production. Copy and enable it:

sudo cp telemetry-deck-mcp.service /etc/systemd/system/
sudo systemctl enable --now telemetry-deck-mcp

Reverse proxy

The server is designed to sit behind a reverse proxy (e.g. Caddy) at a path like /telemetry/. Example Caddy config:

mcp-builder.de {
    handle /telemetry/* {
        uri strip_prefix /telemetry
        reverse_proxy localhost:8083
    }
}

Tools

get_tql_guide

Return the TQL (TelemetryDeck Query Language) reference. Has no parameters. Call this once per session before constructing queries.

list_apps

List the apps available for querying. Has no parameters. Returns a JSON array of {appId, appName} objects, one per *-StructuralData.json file bundled in the package.

get_app_structure

Return the StructuralData (events + parameters + description) for a given app.

Parameters:

Name	Type	Description
app_id	string	The TelemetryDeck app ID (from list_apps)

run_query

Execute a TQL query against TelemetryDeck. Pass a full TQL JSON object — supports timeseries, topN, groupBy, funnel, retention, scan, and experiment query types.

Parameters:

Name	Type	Description
bearer_token	string	Your TelemetryDeck bearer token
app_id	string	The TelemetryDeck app ID to query
query	object	Full TQL query object

Example query:

{
  "queryType": "timeseries",
  "dataSource": "CalculatedSignals",
  "filter": {
    "type": "selector",
    "dimension": "appID",
    "value": "<app_id>"
  },
  "aggregations": [
    {"type": "count", "name": "count"}
  ],
  "granularity": "day",
  "intervals": ["2025-01-01/2025-01-31"]
}

get_insight_query

Retrieve the TQL query object for a saved insight by its ID. Useful for inspecting or re-executing saved insights.

Parameters:

Name	Type	Description
bearer_token	string	Your TelemetryDeck bearer token
app_id	string	The TelemetryDeck app ID
insight_id	string	UUID of the saved insight
days_back	int	Number of days to look back (default: 30)

Authentication

run_query and get_insight_query require bearer_token and app_id. The reference tools (get_tql_guide, list_apps, get_app_structure) take no authentication. Get your bearer token from the TelemetryDeck dashboard or via the login tool.

Testing

Use the MCP Inspector to test the server interactively:

uv run mcp dev src/telemetry_deck_mcp/server.py