trackmcp
Back to directory

A lightweight CLI and MCP server for automating Looker workflows, CI pipelines, and AI-assisted LookML development.

2 stars PythonAI & Machine Learning Updated Oct 17, 2025

Documentation

lookerctl

> Comprehensive CLI for managing and optimizing LookML at scale

📚 **Complete Documentation** - Start here for full documentation

Quick Start

bash
# 1. Setup environment
source .env

# 2. Test connection
lookerctl test

# 3. Export LookML
lookerctl export all --output-dir ./lookml

# 4. Perform static analysis and validation (fast!)
lookerctl validate static ./lookml

# 5. Analyze usage
lookerctl analyze usage

Key Features

  • ⚡ 66x Faster Validation - Local validation in 600ms vs 40s with API for a large-scale looker instance
  • 🔄 Complete Local Development - Export → Edit → Validate → Push workflow
  • 📊 Usage Analysis - Understand which fields users actually use
  • 🧪 Scientific Testing - AB testing and golden tests for confidence, complementing Looker's built-in data tests
  • 🔍 Dependency Mapping - Understand impact before making changes
  • 🤖 AI-Ready - All outputs in JSON for AI consumption
  • 🔌 MCP Server - 20 tools for AI agents via Model Context Protocol

Documentation

Getting Started

Reference

Examples

Example Workflows

Local Development

bash
# Sync with local git branch
lookerctl session sync my-project

# Export to local
lookerctl export project my-project -o ./local

# Make changes
vim ./local/views/users.view.lkml

# Validate (600ms!)
lookerctl validate static ./local

# Push to Looker
lookerctl export push my-project ./local

AB Testing Optimization

bash
# Create baseline BEFORE changes
lookerctl query-test baseline create model.explore \
  -q query.json -o before.json

# Make optimization changes
# ... optimize SQL, add indexes ...

# Compare AFTER changes
lookerctl query-test baseline compare model.explore \
  -b before.json

# Result: ✓ 39% faster with no data changes!

Usage Analysis

bash
# Analyze what's being used
lookerctl analyze usage -o usage.json

# Find unused explores
lookerctl analyze unused

# Build dependency graph
lookerctl deps build ./lookml -o deps.json

MCP Server for AI Agents

bash
# Start MCP server (for Claude Desktop)
lookerctl mcp

# Add to Claude Desktop config:
# {
#   "mcpServers": {
#     "looker": {
#       "command": "/path/tlookerctl",
#       "args": ["mcp"],
#       "env": { ... }
#     }
#   }
# }

# Then ask Claude:
# "List all Looker projects"
# "Find unused explores"
# "Analyze dependencies in ./lookml"

Installation

bash
# 1. Install dependencies
uv pip install -r requirements.txt

# 2. Configure credentials (.env file)
export LOOKERSDK_BASE_URL=https://your-instance.looker.com:443
export LOOKERSDK_CLIENT_ID=your_client_id
export LOOKERSDK_CLIENT_SECRET=your_client_secret

# 3. Test connection
lookerctl test

Performance

OperationAPI MethodLocal GraphSpeedup
Validate project40s600ms66x faster
Field discovery2s100ms20x faster
Dependency check5s50ms100x faster

Architecture

code
TODO: populate architecture diagram

Key Commands

bash
# Session management
lookerctl session sync
lookerctl session workspace dev

# Export/Push
lookerctl export all -o ./lookml
lookerctl export push my-project ./lookml

# Validation
lookerctl validate static ./lookml     # 600ms
lookerctl validate local my-project ./lookml   # 40s, accurate

# Analysis
lookerctl analyze usage
lookerctl deps build ./lookml

# Testing
lookerctl query-test baseline create model.explore -q query.json
lookerctl query-test baseline compare model.explore -b baseline.json
lookerctl query-test golden run

Use Cases

For Developers

  • Local development workflow like Looker console
  • Fast validation during iteration
  • Safe refactoring with baselines
  • Impact analysis before changes

For AI Systems

  • MCP server with 20 tools for AI agents
  • Export all LookML for analysis
  • Programmatic field discovery
  • Automated optimization with validation
  • Scientific testing of improvements

For Teams

  • Visibility into user-created content
  • CI/CD integration with golden tests
  • Performance tracking over time
  • Automated optimization pipelines

Support

  • 📖 Documentation: See docs/
  • 🐛 Issues: Report via your team's issue tracker
  • ❓ Help: Start with Getting Started

Status

Production Ready

  • All features tested end-to-end
  • Complete AB testing workflow validated
  • 66x faster local validation
  • Comprehensive documentation
  • Full error handling

Version: 0.1.0

Last Updated: 2025-10-11

For complete documentation, see: docs/README.md

Frequently asked questions

What is lookerctl?

lookerctl is A lightweight CLI and MCP server for automating Looker workflows, CI pipelines, and AI-assisted LookML development.

How do I install lookerctl?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is lookerctl open source?

Yes — it is hosted on GitHub at https://github.com/z3z1ma/lookerctl and has 2 stars.

Related MCP tools

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP