数据镜头-MCP
Yandex DataLens Public API的Rust MCP服务器(https://api.datalens.tech).
此服务器使用MCP stdio 将DataLens RPC方法作为MCP工具进行传输和公开。
快速开始
从哪里开始 datalens-mcp:
- 安装MCP服务器:
- Linux(x86_64,tar.gz) - Fedora Linux(RPM) - Debian/Ubuntu Linux(DEB) - macOS(苹果硅,aarch64 tar.gz) - Windows(MSI或ZIP) - 从源代码构建
- 获取API凭据(组织ID+IAM令牌):
- 获取API凭据
- 将MCP服务器连接到您使用的代理:
- Codex CLI - VS代码法典扩展 - 光标 - 克劳德代码(CLI) - 克劳德桌面
- 运行第一个请求:
- 使用示例
免责声明
- 这是一个非官方的、由社区维护的项目,与Yandex没有关联、赞助或认可。
- Yandex和DataLens是其各自所有者的商标。
- 名字
datalens-mcp仅用于描述与DataLens API的兼容性。
支持的工具
- 公用设施:
- datalens_list_methods:返回完整的DataLens RPC方法目录(目前为60个方法)、映射的MCP工具名称、类别和快照元数据。 - datalens_get_method_schema:返回请求模式、调用提示和嵌入式静态 requestExample / responseExample 来自捆绑的OpenAPI快照的值。 - datalens_rpc:下任何方法的通用回退 /rpc/{method}.
- 打字包装(核心高频法):
- datalens_get_connection -> getConnection - datalens_create_connection -> createConnection - datalens_get_dashboard -> getDashboard - datalens_get_dataset -> getDataset - datalens_create_dataset -> createDataset - datalens_validate_dataset -> validateDataset - datalens_get_entries -> getEntries - datalens_get_entries_relations -> getEntriesRelations - datalens_get_entries_permissions -> getEntriesPermissions - datalens_get_wizard_chart -> getWizardChart - datalens_get_workbook -> getWorkbook - datalens_get_editor_chart -> getEditorChart - datalens_get_ql_chart -> getQLChart - datalens_list_directory -> listDirectory
API覆盖范围
覆盖快照日期: 2026年2月18日.
- 完整方法目录:
- datalens_list_methods 从OpenAPI快照中公开完整的RPC目录(60 目前的方法)。 - datalens_get_method_schema 从嵌入式快照返回请求模式、调用元数据和静态示例。
- 保险单类型:
- 此服务器仅保留用于核心高频操作的键入包装器。 - 这是有意的:它保留了MCP tools/list 更小并保存模型上下文窗口。
- 正向兼容性:
- datalens_rpc 可以调用所有目录方法,包括没有专用类型化包装器的方法。 - datalens_rpc 还可以调用在添加专用包装之前可能稍后出现在DataLens API中的方法。
- 实验方法:
- DataLens文档中标记为实验的方法仍然可以在目录中找到。他们的行为可以在上游改变。
用于此快照的参考文档包括更新至的DataLens API页面 2026年2月4日 (API启动)和方法页面在 2025年6月26日 和 2026年1月16日.
需求
- 防锈(如果从源头构建)
- DataLens组织ID
- Yandex Cloud IAM令牌(或DataLens接受的OAuth令牌)
获取API凭据
DataLens Public API需要身份验证头和组织ID。
来自Yandex文档:
- API调用所需的角色:
datalens.admin或datalens.editor. - 常见的必需标题包括:
- x-dl-org-id - x-dl-api-version - 身份验证令牌头(x-dl-auth-token;此服务器还发送 x-yacloud-subjecttoken)
选择一个令牌路径:第2节(yc CLI),第3节(OAuth->IAM),或 第4节 (服务帐户)。\ 所有这些都必须以IAM令牌结尾 YC_IAM_TOKEN (或 DATALENS_IAM_TOKEN).
1.获取您的DataLens组织ID
官方文件:
- 打开Yandex云控制台。
- 在顶部面板中,单击您的组织名称。
- 单击组织行打开详细信息。
- 复制组织ID。
您将使用此值作为 DATALENS_ORG_ID.
2.获取令牌的最快方法(供本地/开发人员使用)
官方文件:
- CLI安装:
- 创建IAM令牌:
- 安装并初始化
ycCLI(yc init). - 运行:
yc iam create-token- 将输出用作
YC_IAM_TOKEN.
重要提示:IAM令牌过期。过期后刷新。
3.没有YC CLI的替代方案(OAuth->IAM令牌)
官方文件:
- 帐户IAM令牌(OAuth交换):
- IAM API方法(
iam/v1/tokens):
如果不想安装,请使用此路径 yc 当地。
- 登录您的Yandex帐户。
- 打开Yandex OAuth,点击 允许,并复制OAuth令牌:
-
- 将OAuth令牌替换为IAM令牌:
curl \
--request POST \
--header 'Content-Type: application/json' \
--data '{"yandexPassportOauthToken":""}' \
https://iam.api.cloud.yandex.net/iam/v1/tokens- 从JSON响应中,取
iamToken并将其设置为YC_IAM_TOKEN:
export YC_IAM_TOKEN=""PowerShell变体:
$yandexPassportOauthToken = ""
$Body = @{ yandexPassportOauthToken = "$yandexPassportOauthToken" } | ConvertTo-Json -Compress
$env:YC_IAM_TOKEN = (Invoke-RestMethod -Method 'POST' -Uri 'https://iam.api.cloud.yandex.net/iam/v1/tokens' -Body $Body -ContentType 'Application/json').iamToken重要提示:
OAuth_token与IAM token.- 对于此服务器,始终使用生成的IAM令牌
YC_IAM_TOKEN(或DATALENS_IAM_TOKEN). - IAM令牌过期(最多12小时)。过期后刷新。
4.自动化友好路径(服务帐户+密钥)
官方文件:
- 创建服务帐户:
- 分配角色:
- 创建授权密钥:
- 获取服务帐户的IAM令牌:
- 打开Yandex云控制台。
- 首选 身份及访问管理 -> 服务账户.
- 点击 创建服务帐户.
- 设置名称,单击 创建.
- 在角色分配中,单击 添加角色,则授予至少一个DataLens API角色(
datalens.editor或datalens.admin). - 打开已创建的服务帐户。
- 点击 创建新密钥 -> 创建授权密钥.
- 点击 创建 并下载密钥文件。
- 使用链接文档中的官方说明将此密钥兑换为IAM令牌。
将结果值用作:
DATALENS_ORG_IDYC_IAM_TOKEN或DATALENS_IAM_TOKEN
5.应用密钥设置的位置
下面的安装部分包括在Linux、macOS和Windows上设置这些值的特定于平台的命令。
按平台安装
发布工件发布在 .
Linux(x86_64,tar.gz)
- 从下载Linux存档 .
- 安装二进制文件:
tar -xzf datalens-mcp--x86_64-unknown-linux-gnu.tar.gz
sudo install -m 0755 datalens-mcp /usr/local/bin/datalens-mcp- 为此平台配置凭据:
# persistent
export DATALENS_ORG_ID=""
# refresh per session (recommended for user tokens)
export YC_IAM_TOKEN="$(yc iam create-token)"可选持久性 DATALENS_ORG_ID:
echo 'export DATALENS_ORG_ID=""' >> ~/.bashrcFedora Linux(RPM)
- 从下载RPM .
- 安装:
sudo dnf install ./datalens-mcp-*.rpm- 为此平台配置凭据:
export DATALENS_ORG_ID=""
export YC_IAM_TOKEN="$(yc iam create-token)"Debian/Ubuntu Linux(DEB)
- 下载
.deb从 . - 安装:
sudo apt install ./datalens-mcp_*_amd64.deb- 验证二进制文件和手册页:
which datalens-mcp
man datalens-mcp- 为此平台配置凭据:
export DATALENS_ORG_ID=""
export YC_IAM_TOKEN="$(yc iam create-token)"macOS(苹果硅,aarch64 tar.gz)
- 从下载macOS存档 .
- 安装二进制文件:
tar -xzf datalens-mcp--aarch64-apple-darwin.tar.gz
sudo install -m 0755 datalens-mcp /usr/local/bin/datalens-mcp- 为此平台配置凭据:
export DATALENS_ORG_ID=""
export YC_IAM_TOKEN="$(yc iam create-token)"可选持久性 DATALENS_ORG_ID:
echo 'export DATALENS_ORG_ID=""' >> ~/.zshrcWindows(MSI或ZIP)
选项A:MSI
- 下载
.msi从 . - 运行安装程序。
选项B:ZIP
- 下载
.zip从 . - 提取
datalens-mcp.exe. - 把它放在一个文件夹里
PATH.
为此平台配置凭据(PowerShell):
# persistent
setx DATALENS_ORG_ID ""
# current session
$env:YC_IAM_TOKEN = yc iam create-token从源代码构建(任何平台)
git clone https://github.com/snevolin/datalens-mcp.git
cd datalens-mcp
cargo build --release二进制路径:
- Linux/macOS:
target/release/datalens-mcp - 窗户:
target\release\datalens-mcp.exe
手动运行
Linux/macOS:
export DATALENS_ORG_ID=""
export YC_IAM_TOKEN="$(yc iam create-token)"
datalens-mcpWindows(PowerShell):
$env:DATALENS_ORG_ID = ""
$env:YC_IAM_TOKEN = yc iam create-token
datalens-mcp.exe以MCP服务器身份连接
为您的平台/软件包使用已安装的二进制路径:
- RPM/DEB安装:
/usr/bin/datalens-mcp - tar.gz/手动安装:
/usr/local/bin/datalens-mcp
法典
Codex CLI
建议用于Codex CLI和VS Code Codex扩展:添加服务器时在MCP配置中显式设置env值。
codex mcp remove datalens
codex mcp add datalens \
--env DATALENS_ORG_ID= \
--env YC_IAM_TOKEN= \
--
验证:
codex mcp list
codex mcp get datalens --jsonCLI专用替代方案(会话环境):在运行的同一shell中设置凭据 codex:
Linux/macOS:
export DATALENS_ORG_ID=""
export YC_IAM_TOKEN="$(yc iam create-token)"Windows(PowerShell):
$env:DATALENS_ORG_ID = ""
$env:YC_IAM_TOKEN = yc iam create-token添加服务器:
codex mcp add datalens --
这在不继承shell变量的IDE环境中可能不起作用。
注意:如果在配置中存储直接令牌,则必须在过期后更新它。对于长时间运行的设置,首选服务帐户令牌自动化(请参阅 第4节).
VS代码法典扩展
官方文件:
- Codex MCP设置:
扩展中的MCP设置使用与CLI相同的Codex配置。
选项A:通过UI表单进行配置(连接到自定义MCP).
- 打开Codex面板并单击齿轮图标。
- 打开 MCP设置->打开MCP设置.
- 在 MCP服务器,单击 添加服务器 在 自定义服务器 部分。
- 在 连接到自定义MCP 表单,填写字段:
- 名字: datalens - 运输: STDIO - 发射命令: - 参数:留空 - 凭证模式:使用以下两个选项之一: - 将值存储在此表单中 (推荐):设置 Environment variables 到 DATALENS_ORG_ID= 和 YC_IAM_TOKEN=;离开 Environment variable passthrough 空 - 传递现有的VS代码环境:离开 Environment variables 空;在 Environment variable passthrough 仅添加变量名: DATALENS_ORG_ID 和 YC_IAM_TOKEN (或 DATALENS_IAM_TOKEN).当变量已经在表单外部管理时(例如通过shell配置文件, direnv、devcontainer/CI env、secret manager),并且您不希望在扩展设置中存储令牌值 - 工作目录:可选,默认值很好
- 点击 保存 如果MCP服务器没有立即显示,则重新启动VS Code。
对于Windows,设置 发射命令 致你的 .exe例如: C:\\Program Files\\datalens-mcp\\datalens-mcp.exe
选项B:通过配置 config.toml.
- 在扩展UI中,打开Codex面板,单击齿轮图标,然后选择 MCP设置->打开config.toml.
- 选择范围:
- 用户范围: ~/.codex/config.toml - 项目范围: .codex/config.toml (仅限受信任的项目)
- 添加此配置(替换占位符):
[mcp_servers.datalens]
command = "
"
args = []
[mcp_servers.datalens.env]
DATALENS_ORG_ID = ""
YC_IAM_TOKEN = ""对于Windows,设置 command 致你的 .exe例如: C:\\Program Files\\datalens-mcp\\datalens-mcp.exe
- 保存
config.toml如果MCP服务器没有立即显示,则重新启动VS Code。
VS Code终端的等效设置:
codex mcp remove datalens
codex mcp add datalens \
--env DATALENS_ORG_ID= \
--env YC_IAM_TOKEN= \
--
光标
官方文件:
- 光标MCP概述:
- MCP配置(
mcp.json):
您可以在以下位置配置MCP:
- 项目范围:
.cursor/mcp.json(与此仓库共享) - 用户范围:
~/.cursor/mcp.json(所有项目) - Windows上的用户范围:
%USERPROFILE%\\.cursor\\mcp.json(PowerShell:$HOME\\.cursor\\mcp.json)
配置示例:
{
"mcpServers": {
"datalens": {
"type": "stdio",
"command": "
",
"args": [],
"env": {
"DATALENS_ORG_ID": "",
"YC_IAM_TOKEN": ""
}
}
}
}对于Windows,设置 command 致你的 .exe 路径,例如: C:\\Program Files\\datalens-mcp\\datalens-mcp.exe
在游标代理中验证(可选):
cursor-agent mcp list
cursor-agent mcp list-tools datalens克劳德代码(CLI)
官方文件:
添加服务器:
claude mcp add datalens --
如果需要,传递显式的env值:
claude mcp add datalens \
--env DATALENS_ORG_ID= \
--env YC_IAM_TOKEN= \
--
克劳德桌面
官方文件:
- Claude MCP概述:
- 本地服务器配置流和配置文件位置:
单击路径:
- 打开克劳德桌面。
- 打开 设置.
- 打开 开发者 选项卡。
- 点击 编辑配置.
配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户:
%APPDATA%\Claude\claude_desktop_config.json
配置示例:
{
"mcpServers": {
"datalens": {
"command": "
",
"args": [],
"env": {
"DATALENS_ORG_ID": "",
"YC_IAM_TOKEN": ""
}
}
}
}对于Windows,设置 command 致你的 .exe 路径,例如: C:\\Program Files\\datalens-mcp\\datalens-mcp.exe
使用示例
安装和MCP连接后,在代理中尝试以下常见的DataLens任务:
- 库存仪表板:
Show all dashboards in my workspace with folder, owner, and last update date.- 审核过时对象:
Find dashboards and datasets that were not updated in the last 90 days.- 检查一个仪表板:
Open dashboard "" and summarize its charts, widgets, and selectors.- 检查一个数据集:
Open dataset "" and summarize fields, calculated fields, and joins.- 检查访问权限:
Show who can view and edit entry "".- 更改前运行影响分析:
For dataset "", list dashboards and charts that depend on it.环境变量
DATALENS_ORG_ID(必填)YC_IAM_TOKEN或DATALENS_IAM_TOKEN(必填)DATALENS_BASE_URL(可选,默认https://api.datalens.tech)DATALENS_API_VERSION(可选,默认0)DATALENS_TIMEOUT_SECONDS(可选,默认30)
备注
- API文档同时使用
api.datalens.tech和api.datalens.yandex.net在不同的地方;此服务器默认为api.datalens.tech但允许您覆盖基本URL。 - 对于长时间运行的设置,首选基于服务帐户的令牌流和轮换自动化(请参见 第4节).
许可证
Apache-2.0(见 LICENSE).
主要参考文献
- DataLens Public API启动:
- DataLens OpenAPI参考索引:
- 组织ID:
- IAM:服务帐户快速入门:
- IAM:为服务帐户分配角色:
- IAM:管理授权密钥:
- IAM:为服务帐户创建令牌:
- IAM:从OAuth令牌创建帐户令牌:
- IAM API:
IamToken/create: - IAM:通过CLI创建令牌(
yc iam create-token): - 食品法典委员会MCP文件:
- 克劳德代码MCP文档:
- MCP本地服务器连接指南(Claude Desktop配置流程):
- 光标MCP文档:
- 光标MCP配置文档:
