Datadata Manual

datadata-manual 是 Datadata 平台的交互式操作手册，通过 MCP（Model Context Protocol）Server 直接调用平台能力。AI Agent 可以像调用本地工具一样搜索数据源、执行查询、管理 Data Spaces。

生成独立 Python 脚本（爬虫/ETL/批处理）请使用 datadata-rest-api skill。 MCP 专为聊天交互设计，不适用于生成独立运行的脚本文件。

安装

npx skills add datadata-team/datadata-skills

安装后 Agent 就能通过下列 MCP 工具与 Datadata 交互。

MCP 端点

https://www.datadata.com/api/mcp/v1

认证方式

OAuth 2.0（推荐）

配置 MCP 客户端时选择 OAuth 方式，浏览器自动跳转至 Datadata 完成授权。这是最规范、最便捷的方式，支持 Claude Desktop、VS Code、Cursor、Windsurf、Claude Code 等 MCP 客户端。

API Key 认证

也可通过 API Key 进行认证：

1. 登录 datadata.com → 设置 → API Keys
2. 创建新 Key，勾选所需权限
3. 配置到 MCP 客户端

推荐权限：

权限	用途
queries:execute-adhoc	运行 SQL/DQL 查询
executions:get	获取查询结果
datasources:read	读取数据源信息
datasources:scan	扫描数据源结构
datasources:replace-file	替换数据源文件
data-spaces:write	管理数据空间的表与数据

MCP 工具

数据源查找与元数据

工具	用途	关键参数
search-datasource	搜索数据源	search — 用户名或关键词
get-datasource-info	获取数据源元信息	datasourceId
list-tables	列出表和视图	datasourceId, schemaName（可选）
describe-table	获取表列结构（缓存元数据，含注释）	datasourceId, schemaName, tableName
scan-datasource	触发异步 Schema 扫描	datasourceId
set-table-comment	设置表/列注释	datasourceId, schemaName, tableName

数据查询

工具	用途
execute-adhoc	执行 SQL/DQL 查询，返回执行 ID 和结果下载链接

Data Spaces 管理

工具	用途	关键参数
dataspace-create	创建数据空间（dataspace 类型数据源）	name, displayName, description, visibility, tags（可选）
dataspace-execute-sql	在数据空间中执行任意 DuckDB SQL（建表 / 写入 / 改表 / 删表）	datasourceId, sql, args（可选）

数据空间是一个独立的 DuckDB 数据库，所有表结构与数据变更都通过 dataspace-execute-sql 用 SQL 完成；改动 schema 后建议调用 scan-datasource 刷新元数据。

查询引擎与 SQL 编写

引擎选择

• 默认使用 duckdb 引擎
• 仅针对 ClickHouse 数据源时切换为 clickhouse
• DuckDB 支持跨数据源关联；ClickHouse 不支持

数据源绑定

通过 datasources 参数绑定数据源，格式：

["DATASOURCE_ID:ATTACH_ALIAS"]

SQL 中通过别名而非 datasource ID 引用表。

表命名约定

数据空间（dataspace 类型）：

"{attachAlias}".main."{tableName}"

其中 main 是 DuckDB 固定 schema，attachAlias 为挂载别名（惯例复用数据源名称）。

数据库数据源（MySQL、PostgreSQL 等）：

attachAlias.schemaName.tableName

文件数据源（CSV、JSON、Parquet 等）：

memory.main.attachAlias

Data Spaces（数据空间）

Data Spaces 是 dataspace 类型 datasource 独有的能力：用 dataspace-create 创建数据空间，用 dataspace-execute-sql 在其中执行任意 DuckDB SQL 管理表结构与数据。

读 / 写分离：写入（建表 / 改表 / 写数据）走 dataspace-execute-sql（同步执行）；查询读取走 execute-adhoc（把数据空间作为只读数据源挂载）。

完整工作流

dataspace-create（创建数据空间）
  → dataspace-execute-sql（CREATE TABLE 建表）
  → dataspace-execute-sql（INSERT 写入）
  → execute-adhoc（挂载数据空间查询验证）
  → dataspace-execute-sql（DROP TABLE 清理）

结果处理

execute-adhoc 返回执行 ID 和结果下载链接（NDJSON/CSV）。Agent 用 curl 下载到本地预览。

不要直接将完整的大数据集读入上下文。

配置示例

{
  "mcpServers": {
    "datadata": {
      "command": "npx",
      "args": ["-y", "@datadata/mcp-server"],
      "env": {
        "DATADATA_API_KEY": "ak_xxxxxxxxxxxxxxxx"
      }
    }
  }
}