Get the AI Analyst running and ask your first question in under 5 minutes.
Before starting, make sure you have:
- Claude Desktop OR ChatGPT Desktop (or both!)
- Claude Desktop → Download here
- ChatGPT Desktop → Download here
- Python 3.10 or higher installed
# Check your version python3 --version # Should show: Python 3.10.x or higher
- 5 minutes of your time
UV is a fast Python package manager. Install it with one command:
curl -LsSf https://astral.sh/uv/install.sh | shpowershell -c "irm https://astral.sh/uv/install.ps1 | iex"Verify installation:
uv --version
# Should show: uv x.x.x# Clone the repository
git clone https://github.com/sbdk-dev/claude-analyst.git
cd claude-analyst/semantic-layer
# Install dependencies (this creates a virtual environment and installs everything)
uv sync
# Verify installation
uv run python -c "print('Installation successful!')"Expected output: Installation successful!
# Run the setup script (creates config with absolute path)
./scripts/setup_claude_desktop.shExpected output:
Claude Desktop configured!
Config location: ~/Library/Application Support/Claude/claude_desktop_config.json
Restart Claude Desktop to activate
-
Find your config file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
-
Get your full path to the semantic-layer directory:
pwd # Copy this output - you'll need it in the next step
-
Find the full path to uv:
which uv # Common locations: # macOS (Homebrew): /opt/homebrew/bin/uv # macOS (curl install): ~/.cargo/bin/uv # Linux: ~/.cargo/bin/uv # Windows: %USERPROFILE%\.cargo\bin\uv.exe
-
Edit the config file and add this (replace paths with your actual paths):
{ "mcpServers": { "ai-analyst": { "command": "/opt/homebrew/bin/uv", "args": ["run", "python", "run_mcp_server.py"], "cwd": "/FULL/PATH/TO/claude-analyst/semantic-layer" } } }Important:
- Use the full path to
uv(fromwhich uv) - Use the full path to your semantic-layer directory (from
pwd) - GUI apps don't inherit your shell's PATH, so
"command": "uv"won't work
- Use the full path to
-
Save the file (make sure it's valid JSON - no trailing commas!)
-
Restart Claude Desktop and proceed to Step 4.
-
Set your OpenAI API key:
export OPENAI_API_KEY="sk-your-key-here"
To make this permanent, add it to your shell profile:
echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.zshrc source ~/.zshrc
-
Start the OpenAI API server:
cd semantic-layer uv run python run_openai_server.pyExpected output:
AI Analyst OpenAI API Server Starting server on http://localhost:8000 -
Configure ChatGPT Desktop:
- Open ChatGPT Desktop
- Go to Settings → Beta Features → Enable "Actions"
- Add a new Custom Action:
- Name: AI Analyst
- URL:
http://localhost:8000 - Auth: None (or Bearer token if you set one)
-
Test it: In ChatGPT, ask "List available data models"
Note: Keep the terminal running while using ChatGPT Desktop. The server needs to be active.
Before using your AI desktop, verify everything works locally:
cd semantic-layer
# Test 1: Check database exists
ls -la data/analytics.duckdb
# Should show: analytics.duckdb file exists
# Test 2: Verify semantic models load
uv run python -c "
from mcp_server.semantic_layer_integration import SemanticLayerManager
import asyncio
async def test():
manager = SemanticLayerManager()
await manager.initialize()
models = await manager.get_available_models()
print(f'SUCCESS: {len(models)} models loaded')
print(f'Available: {[m[\"name\"] for m in models]}')
asyncio.run(test())
"Expected output:
SUCCESS: 3 models loaded
Available: ['users', 'events', 'engagement']
If you see this, you're ready! If not, see Troubleshooting below.
- Restart Claude Desktop (Cmd+Q on Mac, then reopen)
- Wait 5 seconds for the MCP server to initialize
- Try your first query:
List available data models
- Make sure the server is running (from Step 3)
- Open ChatGPT Desktop
- Try your first query:
List available data models
Expected response: Both will list the 3 semantic models (users, events, engagement).
Now try these queries to explore the system:
How many users do we have?
What's our conversion rate from free to paid?
Show me our user breakdown by plan type
Compare engagement between Pro and Free users
What are the top 5 features by usage?
Show me DAU trend for the last 30 days
Is the difference in conversion rate statistically significant?
Run a comprehensive conversion analysis
Analyze feature adoption patterns across user segments
The AI Analyst provides:
- list_models - See available data models
- get_model - Get detailed schema for a model
- query_model - Run queries with statistical analysis
- suggest_analysis - Get recommendations for next steps
- test_significance - Statistical testing on demand
- ...and 18 more advanced tools
- Conversion Analysis - Full funnel analysis with cohort comparison
- Feature Usage Analysis - Adoption rates and engagement patterns
- Revenue Optimization - LTV, churn prediction, growth opportunities
The system remembers your questions and learns your preferences over a 24-hour window.
Cause: UV not installed or not in PATH
Solution:
# Reinstall UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your terminal, then try again
uv --versionCause: Database hasn't been generated
Solution:
cd semantic-layer
uv run python generate_sample_data.py
uv run python load_to_duckdb.pyCauses:
- Using
"command": "uv"instead of full path to uv - Config file has wrong path
- Config file has invalid JSON syntax
- Claude Desktop not restarted
Solution:
# 1. Find the full path to uv
which uv
# Output: /opt/homebrew/bin/uv (or similar)
# 2. Update config to use FULL PATH:
# Change "command": "uv" to "command": "/opt/homebrew/bin/uv"
# 3. Verify config exists and has correct paths
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# 4. Validate JSON syntax at https://jsonlint.com
# 5. Quit Claude Desktop completely (Cmd+Q)
# 6. Reopen Claude Desktop
# 7. Wait 10 seconds for MCP to initializeWhy this matters: GUI apps on macOS don't inherit your shell's PATH environment variable, so they can't find uv unless you provide the full path.
Cause: Missing OpenAI API key or port already in use
Solution:
# Check API key is set
echo $OPENAI_API_KEY
# Should show your key (not empty)
# If port 8000 is in use, kill the process
lsof -i :8000
kill -9 <PID>
# Restart server
uv run python run_openai_server.pyCause: System has Python 3.9 or older
Solution:
# Install Python 3.10+ from python.org
# Or use pyenv:
brew install pyenv
pyenv install 3.12
pyenv global 3.12
# Verify
python3 --versionCause: Database or semantic models have issues
Solution:
# Run the comprehensive test
cd semantic-layer
uv run python test_all_functionality.py
# Check for error messages
# If tests pass, the issue is in your AI desktop- Run tests:
uv run python test_all_functionality.pyshows what's failing - Ask for help: Open an issue with:
- Your OS and Python version
- Error messages from tests
- Which desktop app you're using
After setup, you should:
- See "SUCCESS: 3 models loaded" from verification test
- Get a response when asking "List available data models"
- See real data when asking "How many users do we have?"
- Get statistical analysis when asking about comparisons
If all checked, you're ready! Start asking questions about your data.
Now that you're set up, explore:
- Try the examples - Ask "Run a comprehensive conversion analysis"
- Learn the workflows - Ask "What workflows are available?"
- Understand the data - Ask "Describe the users model"
- Ask your own questions - The system learns from your queries
Pro tip: Start simple ("How many users?") and build complexity based on results. The system is designed for incremental exploration.
Setup Time: ~5 minutes Questions Answered: Unlimited Statistical Rigor: Automatic
Happy analyzing!