数据分析协议服务器

Lightdash MCP服务器

使用模型上下文协议（MCP）将Claude、Cursor和其他AI助手连接到Lightdash分析。

一种用于交互的模型上下文协议（MCP）服务器 Lightdash，使LLM能够以编程方式发现数据、创建图表和管理仪表板。

特性

此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 .

谷歌云IAP支持

如果你的Lightdash实例落后 谷歌云身份感知代理 （例如，Cloud Run with --iap)，与一起安装 iap 额外：

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

集 IAP_ENABLED=true.服务器将签署JWT（观众 {LIGHTDASH_URL}/*)通过IAM凭据API并将其附加为 Proxy-Authorization: Bearer <jwt> 在每一个请求。这 Authorization: ApiKey Lightdash保留了标题。

支持服务帐户凭据和用户凭据（应用程序默认凭据/ADC）：

服务帐户凭据 （Cloud Run、GCE等中的默认设置）：

• 运行时服务帐户需要 roles/iam.serviceAccountTokenCreator 本身
• 运行时服务帐户需要 roles/iap.httpsResourceAccessor 在Cloud Run服务上

用户凭据（ADC） （例如。 gcloud auth application-default login):

• 集 IAP_SA 发送到服务帐户电子邮件以模拟签名JWT
• 用户需要 roles/iam.serviceAccountTokenCreator 在目标服务帐户上
• 目标服务帐户需要 roles/iap.httpsResourceAccessor 在Cloud Run服务上

配置

环境变量

服务器需要以下环境变量：

获取您的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"
      }
    }
  }
}

使用克劳德代码（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

可用工具

📊 发现和元数据

📈 图表管理

📋 仪表盘管理

🔍 查询执行

🗂️ 资源管理

项目结构

.
├── 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. 分叉存储库
2. 创建要素分支
3. 使用适当的测试添加您的更改
4. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

对于问题和疑问：

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