Lightdash Mcp Server

What is Lightdash Mcp Server about?

Enables AI assistants to query and manipulate Lightdash resources—projects, spaces, charts, dashboards, custom metrics, and catalogs—via the Model Context Protocol (MCP), turning Lightdash into a programmatically accessible data source.

How to use Lightdash Mcp Server?

1. Installation

   npm install lightdash-mcp-server   # or via Smithery
   

2. Run the server (Stdio transport, default)

   npx lightdash-mcp-server
   

   • Configure MCP client JSON to invoke the command and supply LIGHTDASH_API_KEY and LIGHTDASH_API_URL in the env section.
3. Run the server with HTTP transport (optional)

   npx lightdash-mcp-server -port 8080
   

   • Point the MCP client to http://localhost:8080/mcp.
4. Programmatic access

   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);
   

Key Features

• list_projects: enumerate all projects in the Lightdash organization.
• get_project: retrieve details of a specific project.
• list_spaces: list spaces within a project.
• list_charts / list_dashboards: enumerate visual assets.
• get_custom_metrics, get_catalog, get_metrics_catalog: access metric definitions and data catalog.
• get_charts_as_code, get_dashboards_as_code: export visualizations as source code.
• Supports both Stdio (default) and Streamable HTTP transports.
• Fully typed npm package with development scripts, linting, and example usage.

Use Cases

• AI‑driven analytics assistants that can answer natural‑language questions by fetching Lightdash data on‑the‑fly.
• Automated reporting pipelines that retrieve dashboards or charts as code for version‑controlled deployment.
• Custom metric discovery where an LLM explores available metrics and suggests new ones.
• Integration with Claude Desktop or other MCP‑compatible clients to embed Lightdash data within chat‑based workflows.

FAQ

Q: Which environment variables are required? A: LIGHTDASH_API_KEY (Personal Access Token) and LIGHTDASH_API_URL (base API endpoint). They must be available where the server runs.

Q: Do I need to pass the API key in the MCP client config? A: No. The key is supplied via the server’s environment variables, not the client JSON.

Q: Can I run the server in production? A: Yes. Build the package with npm run build and start it via npx lightdash-mcp-server (or run the compiled binary if packaged).

Q: How do I switch between Stdio and HTTP transports? A: Omit the -port flag for Stdio (default). Provide -port <number> to launch the HTTP server.

Q: Are there example scripts? A: See examples/list_spaces_http.ts for a complete HTTP client example.

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