TelemetryDeck MCP Server

A read-only MCP (Model Context Protocol) server for TelemetryDeck analytics. Query your app's usage data directly from Claude Code, Cursor, or any MCP-compatible client.

Features

• 6 tools for querying TelemetryDeck analytics
• Saved Insight execution — run pre-configured dashboard charts by ID
• Raw TQL queries — escape hatch for advanced analysis
• Async polling — handles TelemetryDeck's async query pattern with backoff and timeout
• Auto token refresh — lazy authentication with automatic 401 retry
• Compact results — formats data for LLM consumption (capped at 200 rows)

Tools

Tool	Description
list_insights	List saved insights (dashboard charts) for an app
get_insight_query	Fetch the TQL query definition behind a saved insight
run_saved_insight	Execute a saved insight and return results (preferred)
run_query	Submit a raw TQL query and return results
get_query_status	Check the status of an async query task
get_query_results	Retrieve results of a completed async query

Preferred pattern: Use run_saved_insight to execute pre-configured insights from your TelemetryDeck dashboard instead of writing raw TQL queries.

Setup

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• A TelemetryDeck account with an app configured

Install

git clone https://github.com/saurabhav88/telemetrydeck-mcp.git
cd telemetrydeck-mcp
uv venv && uv pip install -e .

Configure for Claude Code

Add to your ~/.mcp.json:

{
  "mcpServers": {
    "telemetrydeck": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/telemetrydeck-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEMETRYDECK_EMAIL": "your-email@example.com",
        "TELEMETRYDECK_PASSWORD": "your-password",
        "TELEMETRYDECK_APP_ID": "your-app-id-uuid"
      }
    }
  }
}

Then enable it in ~/.claude/settings.local.json:

{
  "enabledMcpjsonServers": ["telemetrydeck"]
}

Environment Variables

Variable	Required	Description
TELEMETRYDECK_EMAIL	Yes	Your TelemetryDeck account email
TELEMETRYDECK_PASSWORD	Yes	Your TelemetryDeck account password
TELEMETRYDECK_APP_ID	No	Default app ID (can be overridden per tool call)

Usage Examples

Once configured, you can ask Claude Code:

• "How many active users do we have this week?"
• "Show me app version distribution for the last 30 days"
• "List all our TelemetryDeck insights"
• "Run the launches insight for the past 7 days"

Claude will use the MCP tools to query TelemetryDeck directly and return formatted results.

Setting Up Insights

For the best experience, create saved insights in your TelemetryDeck dashboard for common metrics:

• App launches
• Daily/weekly active users
• Version distribution
• Error rates
• Feature usage

Then use list_insights to get their IDs and run_saved_insight to execute them.

API Reference

This server uses the TelemetryDeck REST API:

• POST /api/v3/users/login — authenticate
• POST /api/v3/insights/{id}/query/ — get query from saved insight
• POST /api/v3/query/calculate-async/ — submit async query
• GET /api/v3/task/{id}/status/ — poll query status
• GET /api/v3/task/{id}/value/ — retrieve results

Configuration

Setting	Default	Description
Poll timeout	30s	Max time to wait for async query completion
Poll interval	1s	Initial polling interval (backs off with 1.5x factor)
Max rows	200	Result rows capped to prevent context overflow

License

MIT