A lightweight CLI and MCP server for automating Looker workflows, CI pipelines, and AI-assisted LookML development.
2 stars
Python
Updated Oct 17, 2025
Documentation
lookerctl
Comprehensive CLI for managing and optimizing LookML at scale
Quick Links
📚 **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 usageKey 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
- **Getting Started Guide** - Installation and setup
- **Core Concepts** - Understanding the tool
Reference
- **CLI Reference** - Complete command reference
- **Query Testing** - Baselines and AB testing
- **Local Validation** - Fast local validation
- **AI Integration** - AI-driven workflows
- **MCP Server** - Model Context Protocol integration for AI agents
Examples
- **Examples Directory** - Real working examples and templates
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 ./localAB 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.jsonMCP 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 testPerformance
| Operation | API Method | Local Graph | Speedup |
|---|---|---|---|
| Validate project | 40s | 600ms | 66x faster |
| Field discovery | 2s | 100ms | 20x faster |
| Dependency check | 5s | 50ms | 100x faster |
Architecture
code
TODO: populate architecture diagramKey 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 runUse 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
Similar MCP
Based on tags & features
Trending MCP
Most active this week