Using Yandex DataLens with AI agents
You can use AI agents to work with DataLens. These include Claude Code, Codex, OpenCode, and more. To do this, you need to connect DataLens to an AI agent using an MCP server or Python SDK and install skills.
Getting started
- Make sure you have access to Yandex Cloud and DataLens.
- Prepare the object in DataLens the AI agent will use: create a workbook or select an existing one. To test the chart creation scenario, your workbook must contain an accessible dataset.
- Make sure you have the permissions to edit this workbook and the objects the AI agent will use.
Note
We do not recommend using both MCP and SDK for the same task.
Connect DataLens to the AI agent
To connect DataLens to your AI agent, add your MCP server to the AI agent, or install datalens-sdk, a type-safe Python SDK for the DataLens API.
Add the server by running this command:
claude mcp add datalens \
--env DATALENS_ORG_ID=<organization_ID> \
-- npx -y @datalens-tech/mcp@latest
Alternatively, describe the server in the .mcp.json file in the project's root folder to make this configuration general for the command:
{
"mcpServers": {
"datalens": {
"command": "npx",
"args": ["-y", "@datalens-tech/mcp@latest"],
"env": {
"DATALENS_ORG_ID": "<organization_ID>"
}
}
}
}
The same configuration format is used in Claude Desktop in the claude_desktop_config.json file.
Add this section to the ~/.codex/config.toml file:
[mcp_servers.datalens]
command = "npx"
args = ["-y", "@datalens-tech/mcp@latest"]
[mcp_servers.datalens.env]
DATALENS_ORG_ID = "<organization_ID>"
Add the mcp section to the opencode.json file:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"datalens": {
"type": "local",
"command": ["npx", "-y", "@datalens-tech/mcp@latest"],
"environment": {
"DATALENS_ORG_ID": "<organization_ID>"
}
}
}
}
Tip
We recommend using npx for running Node.js, as the package is downloaded on demand and does not require installation. Alternatives include a local build from the repository or global installation using npm install -g @datalens-tech/mcp and the datalens-mcp command.
Run this command:
pip install datalens-sdk
Example
This example assumes that the user uses an active Yandex Cloud CLI profile and refreshes IAM tokens themselves:
from datalens_sdk import DataLensClientYC
with DataLensClientYC() as client:
dataset = client.get.dataset(by_id="<dataset_ID>")
print(dataset.name)
Main features:
client.get: Downloading objects, such as datasets, charts, dashboards, workbooks, and collections.transfer_enabled: Type-safe fluent builders to create objects.- Operations on objects:
.rename(),.update(),.delete(). - Exporting objects' JSON shots to files and creating objects from shots (
client.raw). - Exporting a dashboard together with its dependencies, i.e., charts and datasets.
Authorization methods:
- Yandex Cloud CLI profile (default).
- Service account key, static IAM token.
Warning
The SDK is currently at the alpha version stage (0.x): until release 1.0, minor versions may include incompatible updates. Therefore, we recommend using the SDK together with the datalens-sdk skill for working with AI agents.
Note
The MCP server and SDK support static authorization with a ready-made IAM token. Therefore, you can use AI agents when the Yandex Cloud CLI is not accessible, e.g., in an isolated runtime. The IAM token lifetime is 12 hours. You should refresh it yourself.
Install skills
Install datalens-skills for your AI agent to consider the DataLens object model and select task-appropriate tools.
The skills CLI detects installed AI agents automatically.
Run the following commands:
npx skills add datalens-tech/datalens-skills --skill datalens
npx skills add datalens-tech/datalens-skills --skill datalens-sdk
Tip
Use these flags:
--agent '*': Install all detected AI agents.-g: Globally for all projects.--list: Show the list of available skills.
The repository works as a plugin marketplace.
Run the following commands:
/plugin marketplace add datalens-tech/datalens-skills
/plugin install datalens-skills@datalens
-
Install the CLI version 0.142.0 or higher.
-
Run these installation commands:
codex plugin marketplace add datalens-tech/datalens-skills codex plugin add datalens-skills@datalensWhen installed using a plugin, skill names are prefixed, e.g.,
datalens-skills:datalens-sdk.
Copy the relevant folders from skills/ to the folder scanned by the AI agent:
| AI agent | In projects | Globally |
|---|---|---|
| Claude Code | .claude/skills/ |
~/.claude/skills/ |
| Codex | .agents/skills/ |
~/.agents/skills/ |
| OpenCode | .opencode/skills/ |
~/.config/opencode/skills/ |
Tip
The .agents/skills/ folder is vendor-neutral: both Codex and OpenCode can read it. OpenCode can also read .claude/skills/; therefore, one installation is often enough for multiple AI agents.
Send your request
After connecting DataLens to the AI agent and installing the skills, write a natural language task and specify the IDs of the objects to use.
- Run a new AI agent session.
- Send your request via the AI agent.
Common scenarios
Below you can find examples of requests to an AI agent with installed skills and an MCP server.
-
Dependency audit
Request:
Find all charts and dashboards that use <dataset_ID>.Result: The AI agent will call the navigation commands and Relations API via the MCP.
-
Content cloning
Request:
Clone <dashboard_ID> with all its charts and datasets to <workbook_ID>.Result: The AI agent will write an SDK script with dependency export.
-
Creating from scratch
Request:
Connect to the database, create a dataset with a calculated field for the margin, and build a dashboard with sales by region.Result: The AI agent will create the following chain: connection → dataset → charts → dashboard.
-
Bulk changes
An SDK task: a loop for objects with typed updates.
Request:
In all the workbook's datasets, rename the _revenue_ field to _Revenue_.Result: The AI agent will rename the specified fields.
-
AI report
Request:
Create an HTML report on the quarter results and publish it in DataLens.Result: The
datalens-html-pagesskill will let the agent create, validate, and publish a page.