Lightdash Mcp

Lightdash MCP 服务

使用 Model Context Protocol (MCP) 将 Claude、Cursor 和其他 AI 助手连接到你的 Lightdash 分析平台。

这是一个用于与 Lightdash 交互的 Model Context Protocol (MCP) 服务，可让大模型以编程方式发现数据、创建图表和管理仪表板。

功能

此 MCP 服务提供了一套全面的工具，支持完整的数据分析工作流：

• 发现：浏览数据目录、查找表和探索项，并了解架构
• 查询：执行查询，全面支持筛选器、指标和聚合
• 图表管理：创建、读取、更新和删除图表，支持复杂可视化
• 仪表板管理：构建和管理包含图块、筛选器和布局的仪表板
• 资源整理：创建和管理用于整理内容的空间

安装

前提条件

• Python 3.10+
• 一个 Lightdash 实例（云端或可自托管）
• Lightdash 个人访问令牌（可在 Lightdash 个人资料设置中获取）

使用 pip 快速开始（推荐）

pip install lightdash-mcp

使用 uvx 快速开始

uvx lightdash-mcp

使用 pipx 快速开始

pipx run lightdash-mcp

从源代码安装

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

Google Cloud IAP 支持

如果你的 Lightdash 实例位于 Google Cloud Identity-Aware Proxy 之后（例如，带有 --iap 的 Cloud Run），请使用 iap 扩展安装：

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

设置 IAP_ENABLED=true。服务将通过 IAM Credentials API 签署 JWT（受众为 {LIGHTDASH_URL}/*），并在每个请求中将其作为 Proxy-Authorization: Bearer <jwt> 附加。Lightdash 所需的 Authorization: ApiKey 标头会保留。

支持服务账号凭据和用户凭据（应用默认凭据 / ADC）：

服务账号凭据（Cloud Run、GCE 等环境中的默认方式）：

• 运行时服务账号需要对自身拥有 roles/iam.serviceAccountTokenCreator 角色
• 运行时服务账号需要对 Cloud Run 服务拥有 roles/iap.httpsResourceAccessor 角色

用户凭据（ADC）（例如 gcloud auth application-default login）：

• 将 IAP_SA 设置为用于签署 JWT 的服务账号邮箱，以进行模拟
• 用户需要对目标服务账号拥有 roles/iam.serviceAccountTokenCreator 角色
• 目标服务账号需要对 Cloud Run 服务拥有 roles/iap.httpsResourceAccessor 角色

配置

环境变量

服务需要以下环境变量：

变量	必需	说明	示例
LIGHTDASH_TOKEN	✅	你的 Lightdash 个人访问令牌	ldt_abc123...
LIGHTDASH_URL	✅	Lightdash 实例的基础 URL	https://app.lightdash.cloud
CF_ACCESS_CLIENT_ID	❌	Cloudflare Access 客户端 ID（如果位于 CF Access 之后）	-
CF_ACCESS_CLIENT_SECRET	❌	Cloudflare Access 客户端密钥（如果位于 CF Access 之后）	-
LIGHTDASH_PROJECT_UUID	❌	默认项目 UUID（若未设置，则使用第一个可用项目）	3fc2835f-...
IAP_ENABLED	❌	启用 Google Cloud IAP 身份验证（true/1）	true
IAP_SA	❌	使用用户凭据 (ADC) 时用于 IAP 的服务账号邮箱	[email protected]

获取 Lightdash 令牌

1. 登录 Lightdash 实例
2. 前往 设置 → 个人访问令牌
3. 点击 生成新令牌
4. 复制令牌（以 ldt_ 开头）

在 Claude Desktop 中使用

将以下内容添加到你的 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"
      }
    }
  }
}

在 Claude Code（CLI）中使用

在项目根目录中创建或编辑 .mcp.json：

{
  "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"
      }
    }
  }
}

重启 Claude Code 并运行 /mcp，以确认服务已显示为已连接。

注意：如果 .mcp.json 中包含机密信息，请勿提交该文件——将其添加到 .gitignore。

在其他 MCP 客户端中使用

运行前导出环境变量：

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

可用工具

📊 发现与元数据

工具	描述
list-projects	列出所有可用的 Lightdash 项目
get-project	获取特定项目的详细信息
list-explores	列出项目中所有可用的探索/表
get-explore-schema	获取特定探索的详细架构（维度、指标、联接）
list-spaces	列出项目中的所有空间（文件夹）
get-custom-metrics	获取项目中定义的自定义指标

📈 图表管理

工具	描述
list-charts	列出所有已保存的图表，可按名称筛选
search-charts	按名称或描述搜索图表
get-chart-details	获取特定图表的完整配置
create-chart	使用指标查询和可视化配置创建新的已保存图表
update-chart	更新现有图表的配置（名称、描述、查询、可视化）
run-chart-query	执行图表查询并检索数据
delete-chart	删除已保存的图表

📋 仪表板管理

工具	描述
list-dashboards	列出项目中的所有仪表板
create-dashboard	创建新仪表板（空白或包含图块）
duplicate-dashboard	克隆现有仪表板并指定新名称
get-dashboard-tiles	获取仪表板中的所有图块，可选返回完整配置
get-dashboard-tile-chart-config	获取特定仪表板图块的完整图表配置
get-dashboard-code	以代码形式获取完整的仪表板配置
create-dashboard-tile	向仪表板添加新图块（图表、Markdown 或 loom）
update-dashboard-tile	更新图块属性（位置、大小、内容）
rename-dashboard-tile	重命名仪表板图块
delete-dashboard-tile	从仪表板中移除图块
update-dashboard-filters	更新仪表板级筛选条件
run-dashboard-tiles	并发执行仪表板中的一个、多个或所有图块

🔍 查询执行

工具	描述
run-chart-query	执行已保存图表的查询并返回数据
run-dashboard-tiles	执行仪表板图块的查询（支持批量执行）
run-raw-query	对任意探索执行临时指标查询

🗂️ 资源管理

工具	描述
create-space	创建新空间，以便整理图表和仪表板
delete-space	删除空空间

项目结构

.
├── 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

开发

添加新工具

服务会自动发现并注册 tools/ 目录中的工具。添加新工具的步骤如下：

1. 在 lightdash_mcp/tools/ 中创建新文件（例如，my_new_tool.py）

2. 定义工具：

   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
   

3. 重启服务——工具将自动注册

工具注册表

工具通过 tools/__init__.py 自动发现，该文件会：

• 扫描 tools/ 目录中的 Python 模块
• 导入每个模块（不包括实用工具模块）
• 根据工具的 TOOL_DEFINITION.name 注册工具

测试

你可以通过导入工具来单独测试：

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)

故障排除

身份验证错误

如果看到 401 Unauthorized 错误：

• 确认你的 LIGHTDASH_TOKEN 正确，且以 ldt_ 开头
• 检查令牌是否已过期
• 确保你在 Lightdash 中拥有必要的权限

连接错误

如果遇到连接错误：

• 确认 LIGHTDASH_URL 正确
• 对于 Lightdash Cloud：使用 https://app.lightdash.cloud
• 对于自托管实例：使用 https://your-domain.com
• 如果位于 Cloudflare Access 后方，确保已设置 CF_ACCESS_CLIENT_ID 和 CF_ACCESS_CLIENT_SECRET
• 如果位于 Google Cloud IAP 后方，确保已设置 IAP_ENABLED=true，使用 pip install lightdash-mcp[iap] 安装，并确认服务账号对自身拥有 serviceAccountTokenCreator 权限

未找到工具

如果工具没有显示：

• 检查文件是否位于 tools/ 目录中
• 确保文件包含 TOOL_DEFINITION 变量
• 确认文件未列入 tools/__init__.py 中的排除列表
• 重启 MCP 服务

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 添加更改并提供适当的测试
4. 提交拉取请求

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

• Lightdash 文档
• Lightdash 社区 Slack
• MCP 文档