Lightdash MCP Server

Connect Claude, Cursor, and other AI assistants to your Lightdash analytics using the Model Context Protocol (MCP).

A Model Context Protocol (MCP) server for interacting with Lightdash, enabling LLMs to discover data, create charts, and manage dashboards programmatically.

Features

This MCP server provides a comprehensive set of tools for the full data analytics workflow:

• Discovery: Explore data catalogs, find tables/explores, and understand schemas
• Querying: Execute queries with full filter, metric, and aggregation support
• Chart Management: Create, read, update, and delete charts with complex visualizations
• Dashboard Management: Build and manage dashboards with tiles, filters, and layouts
• Resource Organization: Create and manage spaces for content organization

Installation

Prerequisites

• Python 3.10+
• A Lightdash instance (Cloud or self-hosted)
• Lightdash Personal Access Token (obtain from your Lightdash profile settings)

Quick Start with pip (Recommended)

pip install lightdash-mcp

Quick Start with uvx

uvx lightdash-mcp

Quick Start with pipx

pipx run lightdash-mcp

Install from Source

git clone https://github.com/poddubnyoleg/lightdash_mcp.git
cd lightdash_mcp
pip install .

Google Cloud IAP Support

If your Lightdash instance is behind Google Cloud Identity-Aware Proxy (e.g. Cloud Run with --iap), install with the iap extra:

pip install lightdash-mcp[iap]
# or from source
pip install .[iap]

Set IAP_ENABLED=true. The server will sign a JWT (audience {LIGHTDASH_URL}/*) via the IAM Credentials API and attach it as Proxy-Authorization: Bearer <jwt> on every request. The Authorization: ApiKey header is preserved for Lightdash.

Both service account credentials and user credentials (Application Default Credentials / ADC) are supported:

Service account credentials (default in Cloud Run, GCE, etc.):

• The runtime service account needs roles/iam.serviceAccountTokenCreator on itself
• The runtime service account needs roles/iap.httpsResourceAccessor on the Cloud Run service

User credentials (ADC) (e.g. gcloud auth application-default login):

• Set IAP_SA to the service account email to impersonate for signing the JWT
• The user needs roles/iam.serviceAccountTokenCreator on the target service account
• The target service account needs roles/iap.httpsResourceAccessor on the Cloud Run service

Configuration

Environment Variables

The server requires the following environment variables:

Getting Your Lightdash Token

1. Log into your Lightdash instance
2. Go to Settings → Personal Access Tokens
3. Click Generate new token
4. Copy the token (starts with ldt_)

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "lightdash": {
      "command": "uvx",
      "args": ["lightdash-mcp"],
      "env": {
        "LIGHTDASH_TOKEN": "ldt_your_token_here",
        "LIGHTDASH_URL": "https://app.lightdash.cloud",
        "LIGHTDASH_PROJECT_UUID": "your-project-uuid"
      }
    }
  }
}

Usage with Claude Code (CLI)

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "lightdash": {
      "type": "stdio",
      "command": "lightdash-mcp",
      "env": {
        "LIGHTDASH_URL": "https://your-lightdash-instance.com",
        "LIGHTDASH_TOKEN": "ldt_your_token_here",
        "LIGHTDASH_PROJECT_UUID": "your-project-uuid"
      }
    }
  }
}

Restart Claude Code and run /mcp to verify the server shows as connected.

Note: Don't commit .mcp.json if it contains secrets — add it to .gitignore.

Usage with Other MCP Clients

Export the environment variables before running:

export LIGHTDASH_TOKEN="ldt_your_token_here"
export LIGHTDASH_URL="https://app.lightdash.cloud"
lightdash-mcp

Available Tools

📊 Discovery & Metadata

📈 Chart Management

📋 Dashboard Management

🔍 Query Execution

🗂️ Resource Management

Project Structure

.
├── pyproject.toml              # Package configuration
├── lightdash_mcp/              # Main package
│   ├── __init__.py             # Package init
│   ├── server.py               # MCP server entry point
│   ├── lightdash_client.py     # Lightdash API client
│   └── tools/                  # Tool implementations
│       ├── __init__.py         # Auto-discovery and tool registry
│       ├── base_tool.py        # Base tool interface
│       └── *.py                # Individual tool implementations
├── README.md
└── LICENSE

Development

Adding a New Tool

The server automatically discovers and registers tools from the tools/ directory. To add a new tool:

1. Create a new file in lightdash_mcp/tools/ (e.g., my_new_tool.py)

1. Define the tool:

    from pydantic import BaseModel, Field
    from .base_tool import ToolDefinition
    from .. import lightdash_client as client
    
    class MyToolInput(BaseModel):
        param1: str = Field(..., description="Description of param1")
    
    TOOL_DEFINITION = ToolDefinition(
        name="my-new-tool",
        description="Description of what this tool does",
        input_schema=MyToolInput
    )
    
    def run(param1: str) -> dict:
        """Execute the tool logic"""
        result = client.get(f"/api/v1/some/endpoint/{param1}")
        return result

1. Restart the server - the tool will be automatically registered

Tool Registry

Tools are automatically discovered via tools/__init__.py, which:

• Scans the tools/ directory for Python modules
• Imports each module (excluding utility modules)
• Registers tools by their TOOL_DEFINITION.name

Testing

You can test individual tools by importing them:

from tools import tool_registry

# List all registered tools
print(tool_registry.keys())

# Test a specific tool
result = tool_registry['list-projects'].run()
print(result)

Troubleshooting

Authentication Errors

If you see 401 Unauthorized errors:

• Verify your LIGHTDASH_TOKEN is correct and starts with ldt_
• Check that the token hasn't expired
• Ensure you have the necessary permissions in Lightdash

Connection Errors

If you see connection errors:

• Verify LIGHTDASH_URL is correct
• For Lightdash Cloud: use https://app.lightdash.cloud
• For self-hosted: use https://your-domain.com
• If behind Cloudflare Access, ensure CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET are set
• If behind Google Cloud IAP, ensure IAP_ENABLED=true is set, install with pip install lightdash-mcp[iap], and verify the service account has serviceAccountTokenCreator on itself

Tool Not Found

If a tool isn't showing up:

• Check that the file is in the tools/ directory
• Ensure the file has a TOOL_DEFINITION variable
• Verify the file isn't in the exclusion list in tools/__init__.py
• Restart the MCP server

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add your changes with appropriate tests
4. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Lightdash Documentation
• Lightdash Community Slack
• MCP Documentation