Access Lightdash Data via API

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

examples/list_spaces_http.ts

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

// Load environment variables from .env file
config();

// Get and validate required environment variables
const apiKey = process.env.EXAMPLES_CLIENT_LIGHTDASH_API_KEY;
const apiUrl =
  process.env.EXAMPLES_CLIENT_LIGHTDASH_API_URL ??
  'https://app.lightdash.cloud';

if (!apiKey) {
  throw new Error(
    'EXAMPLES_CLIENT_LIGHTDASH_API_KEY environment variable is required'
  );
}

// Set environment variables for the HTTP server
process.env.LIGHTDASH_API_KEY = apiKey;
process.env.LIGHTDASH_API_URL = apiUrl;

async function main() {
  // Initialize MCP client
  const client = new Client(
    {
      name: 'lightdash-mcp-http-example-client',
      version: '1.0.0',
    },
    {
      capabilities: {},
    }
  );

  // Create HTTP transport to connect to the server
  const transport = new StreamableHTTPClientTransport(
    new URL('http://localhost:8080/mcp')
  );

  try {
    // Connect to the server
    await client.connect(transport);

    // List available tools
    await client.listTools();

    // Call list_spaces with a project UUID
    const projectUuid = process.env.EXAMPLES_CLIENT_LIGHTDASH_PROJECT_UUID;
    if (!projectUuid) {
      throw new Error(
        'EXAMPLES_CLIENT_LIGHTDASH_PROJECT_UUID environment variable is required'
      );
    }

    await client.callTool({
      name: 'lightdash_list_spaces',
      arguments: {
        projectUuid,
      },
    });
  } finally {
    // Close the connection
    await transport.close();
  }
}

main();