# Lightdash MCP Setup

The Lightdash MCP (Model Context Protocol) connector lets Claude explore data models, search fields, run queries, and find dashboards/charts directly in Lightdash.

## Prerequisites

- Lightdash Cloud, Enterprise, or self-hosted instance
- Your Lightdash instance URL (e.g., `https://myorg.lightdash.cloud` or `http://<host>` for self-hosted)
- MCP enabled on the instance (Cloud/Enterprise) — self-hosted may not support MCP

## Setup

### Claude Code CLI

```bash
claude mcp add lightdash https://<your_instance>.lightdash.cloud/api/v1/mcp -t http
```

Replace `<your_instance>` with your Lightdash subdomain.

### Claude Desktop / Claude.ai

1. Settings > Connectors > Add custom connector
2. Name: `Lightdash`
3. URL: `https://<your_instance>.lightdash.cloud/api/v1/mcp`
4. Click Connect and complete the OAuth flow

## Authentication

The MCP connector uses **OAuth 2.0**. When first connecting, you'll be redirected to Lightdash to authorize access. The connector respects all existing Lightdash permissions — Claude can only see and query data the authenticated user has access to.

## Available MCP Tools

Once connected, Claude has access to these tools:

### Project Management
- **list_projects** — list all projects in the organization
- **set_active_project** — switch the active project context
- **get_active_project** — check which project is currently active

### Data Exploration
- **find_explores** — list available explores (tables) in the active project
- **search_fields** — search for specific dimensions and metrics by name or description
- **get_explore** — get detailed information about a specific explore

### Query Execution
- **run_query** — execute a metric query through the semantic layer (uses dimensions and metrics, not raw SQL)
- **run_sql** — execute arbitrary SQL against the warehouse

### Content Discovery
- **find_dashboards** — search for existing dashboards
- **find_charts** — search for existing charts/saved queries

### System
- **get_version** — check the Lightdash instance version

## Recommended Discovery Pattern

When exploring data for dashboard creation:

1. **Start with explores**: `find_explores` to see what tables are available
2. **Examine fields**: `search_fields` or `get_explore` to understand dimensions and metrics
3. **Test queries**: `run_query` with a small set of dimensions/metrics to verify data
4. **Find existing content**: `find_dashboards` and `find_charts` to see what already exists

## Network Requirements

If your organization uses network allowlists, ensure these are permitted:
- Your Lightdash instance URL
- `claudemcpcontent.com` (for visual rendering of query results)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "MCP not available" | Verify MCP is enabled on your Lightdash plan |
| OAuth flow fails | Check the instance URL is correct (include `/api/v1/mcp`) |
| No explores found | Verify the active project has been deployed with `lightdash deploy` |
| Permission errors | The OAuth user needs appropriate Lightdash roles |