Lightdash

What is lightdash-mcp-server?

lightdash-mcp-server is a Model Context Protocol (MCP) server designed to provide AI assistants with standardized access to Lightdash's API. This allows AI models to interact with your Lightdash data, enabling them to retrieve information, list projects, charts, dashboards, and more, all through a unified interface.

How to use lightdash-mcp-server?

lightdash-mcp-server can be installed and configured in two primary ways: via Smithery for automatic installation with Claude Desktop, or manually via npm. It supports both Stdio and HTTP transport modes.

Installation:

• Via Smithery: npx -y @smithery/cli install lightdash-mcp-server --client claude
• Manual Installation: npm install lightdash-mcp-server

Configuration:

Set the following environment variables:

• LIGHTDASH_API_KEY: Your Lightdash Personal Access Token (PAT)
• LIGHTDASH_API_URL: Your Lightdash API base URL

Usage:

• Stdio Transport (Default):

  1. Start the server: npx lightdash-mcp-server
  2. Configure your MCP client (e.g., Claude Desktop) to use the command and args fields to execute the server.

• HTTP Transport (Streamable HTTP):

  1. Start the server in HTTP mode: npx lightdash-mcp-server -port 8080
  2. Configure your MCP client to use the url field, pointing to http://localhost:8080/mcp.
  3. For programmatic access, use @modelcontextprotocol/sdk/client/streamableHttp.js.

Key Features of lightdash-mcp-server

lightdash-mcp-server provides a set of tools that allow AI assistants to interact with Lightdash data:

• list_projects: List all projects in the Lightdash organization.
• get_project: Get details of a specific project.
• list_spaces: List all spaces in a project.
• list_charts: List all charts in a project.
• list_dashboards: List all dashboards in a project.
• get_custom_metrics: Get custom metrics for a project.
• get_catalog: Get catalog for a project.
• get_metrics_catalog: Get metrics catalog for a project.
• get_charts_as_code: Get charts as code for a project.
• get_dashboards_as_code: Get dashboards as code for a project.

Use Cases of lightdash-mcp-server

• AI-powered Data Exploration: Enable AI assistants to answer questions about your Lightdash data by programmatically accessing projects, charts, and dashboards.
• Automated Reporting: Generate reports or summaries based on Lightdash data using AI.
• Integration with AI Tools: Seamlessly integrate Lightdash data into various AI applications and workflows that support the Model Context Protocol.
• Custom AI Assistants: Build custom AI assistants that can retrieve and present Lightdash insights to users.

FAQ about lightdash-mcp-server

Q: What is MCP (Model Context Protocol)? A: MCP is a protocol that allows AI models to interact with external tools and data sources in a standardized way.

Q: Can I use lightdash-mcp-server with other AI clients besides Claude Desktop? A: Yes, any MCP-compatible client can be configured to work with lightdash-mcp-server.

Q: How do I get my Lightdash API Key? A: You can generate a Personal Access Token (PAT) from your Lightdash account settings.

Q: What is the difference between Stdio and HTTP transport modes? A: Stdio (Standard I/O) mode communicates over the command line, while HTTP mode exposes an API endpoint for communication. HTTP mode is suitable for programmatic access and streaming.

Q: Where can I find examples for programmatic access? A: Refer to examples/list_spaces_http.ts in the project repository for a complete example of connecting to the HTTP server programmatically.

lightdash-mcp-server

A MCP(Model Context Protocol) server that accesses to Lightdash.

This server provides MCP-compatible access to Lightdash's API, allowing AI assistants to interact with your Lightdash data through a standardized interface.

Features

Available tools:

• list_projects - List all projects in the Lightdash organization
• get_project - Get details of a specific project
• list_spaces - List all spaces in a project
• list_charts - List all charts in a project
• list_dashboards - List all dashboards in a project
• get_custom_metrics - Get custom metrics for a project
• get_catalog - Get catalog for a project
• get_metrics_catalog - Get metrics catalog for a project
• get_charts_as_code - Get charts as code for a project
• get_dashboards_as_code - Get dashboards as code for a project

Quick Start

Installation

Installing via Smithery

To install Lightdash MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install lightdash-mcp-server --client claude

Manual Installation

npm install lightdash-mcp-server

Configuration

• LIGHTDASH_API_KEY: Your Lightdash PAT
• LIGHTDASH_API_URL: The API base URL

Usage

The lightdash-mcp-server supports two transport modes: Stdio (default) and HTTP.

Stdio Transport (Default)

1. Start the MCP server:

npx lightdash-mcp-server

2. Edit your MCP configuration json:

...
    "lightdash": {
      "command": "npx",
      "args": [
        "-y",
        "lightdash-mcp-server"
      ],
      "env": {
        "LIGHTDASH_API_KEY": "<your PAT>",
        "LIGHTDASH_API_URL": "https://<your base url>"
      }
    },
...

HTTP Transport (Streamable HTTP)

1. Start the MCP server in HTTP mode:

npx lightdash-mcp-server -port 8080

This starts the server using StreamableHTTPServerTransport, making it accessible via HTTP at http://localhost:8080/mcp.

2. Configure your MCP client to connect via HTTP:

For Claude Desktop and other MCP clients:

Edit your MCP configuration json to use the url field instead of command and args:

...
    "lightdash": {
      "url": "http://localhost:8080/mcp"
    },
...

For programmatic access:

Use the streamable HTTP client transport:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:8080/mcp')
);

await client.connect(transport);

Note: When using HTTP mode, ensure the environment variables LIGHTDASH_API_KEY and LIGHTDASH_API_URL are set in the environment where the server is running, as they cannot be passed through MCP client configuration.

See examples/list_spaces_http.ts for a complete example of connecting to the HTTP server programmatically.

Development

Available Scripts

• npm run dev - Start the server in development mode with hot reloading (stdio transport)
• npm run dev:http - Start the server in development mode with HTTP transport on port 8080
• npm run build - Build the project for production
• npm run start - Start the production server
• npm run lint - Run linting checks (ESLint and Prettier)
• npm run fix - Automatically fix linting issues
• npm run examples - Run the example scripts

Contributing

1. Fork the repository
2. Create your feature branch
3. Run tests and linting: npm run lint
4. Commit your changes
5. Push to the branch
6. Create a Pull Request