Treasure Data MCP 服务器

一个提供Claude Code和Claude Desktop与Treasure Data API集成的Model Context Protocol (MCP) 服务器。

免责声明：这是一个个人开发项目，与Treasure Data Inc.没有任何关联、认可或关系。本软件按“原样”提供，不附带任何形式的保证，并且使用风险自负。作者不对因使用此软件而产生的任何后果负责。

参考文档

有关Treasure Data的全面文档和工具：

• 官方API文档: https://api-docs.treasuredata.com/en/overview/gettingstarted/
• CLI工具 (td命令): https://github.com/treasure-data/td
• 控制台界面: https://console.treasuredata.com/
• 详细API指南: docs/treasure-data-api-guide.md

可用的MCP工具

此MCP服务器提供了以下用于与Treasure Data交互的工具：

数据库管理

1. td_list_databases
   python
   td_list_databases(verbose=False, limit=30, offset=0, all_results=False)

   • 获取您Treasure Data账户中的数据库，支持分页

   • 参数:

     • verbose: 如果为True，则返回完整详情；如果为False，则仅返回名称（默认）
     • limit: 要检索的最大数据库数量（默认为30）
     • offset: 开始检索的索引（默认为0）
     • all_results: 如果为True，则忽略limit和offset，检索所有数据库

   • 示例:

     仅获取数据库名称（默认，前30个数据库）

     td_list_databases

     获取完整的数据库详情

     td_list_databases verbose=True

     分页选项

     td_list_databases limit=10 offset=20

     不论数量多少，获取所有数据库

     td_list_databases all_results=True

2. td_get_database
   python
   td_get_database(database_name)

   • 获取特定数据库的详细信息

   • 参数:

     • database_name: 要检索信息的数据库名称

   • 示例:

     获取特定数据库的信息

     td_get_database database_name=my_database_name

3. td_list_tables
   python
   td_list_tables(database_name, verbose=False, limit=30, offset=0, all_results=False)

   • 获取特定Treasure Data数据库中的表，支持分页

   • 参数:

     • database_name: 要从中检索表的数据库名称
     • verbose: 如果为True，则返回完整详情；如果为False，则仅返回名称（默认）
     • limit: 要检索的最大表数量（默认为30）
     • offset: 开始检索的索引（默认为0）
     • all_results: 如果为True，则忽略limit和offset，检索所有表

   • 示例:

     获取数据库中的表名称（默认，前30个表）

     td_list_tables database_name=my_database_name

     获取数据库中表的详细信息

     td_list_tables database_name=my_database_name verbose=True

     分页选项

     td_list_tables database_name=my_database_name limit=10 offset=20

     获取数据库中的所有表

     td_list_tables database_name=my_database_name all_results=True

工作流项目管理

1. td_list_projects
   python
   td_list_projects(verbose=False, limit=30, offset=0, all_results=False, include_system=False)

   • 获取您Treasure Data账户中的工作流项目，支持分页

   • 参数:

     • verbose: 如果为True，则返回完整详情；如果为False，则仅返回名称和ID（默认）
     • limit: 要检索的最大项目数量（默认为30）
     • offset: 开始检索的索引（默认为0）
     • all_results: 如果为True，则忽略limit和offset，检索所有项目- include_system: 如果为 True，则包含系统生成的项目（带有 "sys" 元数据）；默认为 False

   • 示例:

     获取基本项目信息（默认，前 30 个项目）

     td_list_projects

     获取详细的项目信息

     td_list_projects verbose=True

     分页选项

     td_list_projects limit=10 offset=20

     获取所有项目，无论数量多少

     td_list_projects all_results=True

     包含系统生成的项目

     td_list_projects include_system=True

2. td_get_project
   python
   td_get_project(project_id)

   • 获取特定工作流项目的详细信息

   • 注意：这仅提供基本的项目元数据。要获取详细内容和文件，请使用 td_download_project_archive，然后使用 td_list_project_files 和 td_read_project_file

   • 参数:

     • project_id: 要检索信息的工作流项目的 ID

   • 示例:

     获取特定项目的信息

     td_get_project project_id=123456

3. td_download_project_archive
   python
   td_download_project_archive(project_id)

   • 下载项目的归档文件（tar.gz）并返回下载信息

   • 建议用于检查包括 SQL 查询和工作流定义在内的详细项目内容

   • 参数:

     • project_id: 要下载的工作流项目的 ID

   • 示例:

     下载项目的归档文件

     td_download_project_archive project_id=123456

4. td_list_project_files
   python
   td_list_project_files(archive_path)

   • 列出项目归档中包含的所有文件

   • 参数:

     • archive_path: 下载的项目归档文件 (.tar.gz 文件) 的路径

   • 示例:

     列出已下载项目归档中的文件

     td_list_project_files archive_path=/tmp/td_project_123/project_123456.tar.gz

5. td_read_project_file
   python
   td_read_project_file(archive_path, file_path)

   • 从项目归档中读取特定文件的内容

   • 参数:

     • archive_path: 下载的项目归档文件 (.tar.gz 文件) 的路径
     • file_path: 归档内要读取的文件的路径

   • 示例:

     从项目归档中读取特定文件

     td_read_project_file archive_path=/tmp/td_project_123/project_123456.tar.gz file_path=workflow.dig

设置说明

认证

此 MCP 服务器需要 Treasure Data API 密钥进行认证，应通过 TD_API_KEY 环境变量提供。您还可以使用 TD_ENDPOINT 环境变量指定 Treasure Data 终端（默认为 api.treasuredata.com）。

使用 Claude Code 设置

1. 克隆仓库
   bash
   git clone https://github.com/knishioka/td-mcp-server.git
   cd td-mcp-server

2. 安装依赖
   bash

   使用 pip

   pip install -r requirements.txt

   或者使用 uv（推荐）

   uv pip install -e .

3. 设置环境变量并运行
   bash

   设置您的 API 密钥

   export TD_API_KEY="your-api-key"
   export TD_ENDPOINT="api.treasuredata.com" # 可选，默认为美国区域

   运行 MCP 服务器

   mcp run td_mcp_server/server.py

使用 Claude Desktop 设置

通过编辑配置文件 (claude_desktop_config.json) 来配置此 MCP 服务器以与 Claude Desktop 一起使用：

json
{
"mcpServers": {
"td": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/td-mcp-server",
"run",
"td_mcp_server/server.py"
],
"env": {
"TD_API_KEY": "YOUR_API_KEY",
"TD_ENDPOINT": "api.treasuredata.com"
}
}
}
}

安装和需求

该项目需要 Python 3.11+ 以及以下依赖项：- requests>=2.28.0 - 用于API请求的HTTP客户端

• pydantic>=2.0.0 - 数据验证和序列化
• mcp[cli]>=1.8.1 - 模型上下文协议框架

安装依赖项：

bash

使用pip

pip install -r requirements.txt

使用uv（推荐用于开发）

uv pip install -e .

直接运行服务器

你可以直接运行MCP服务器：

bash

设置你的API密钥

export TD_API_KEY="your-api-key"

对于美国区域（默认）

export TD_ENDPOINT="api.treasuredata.com"

对于日本区域

export TD_ENDPOINT="api.treasuredata.co.jp"

使用MCP CLI运行

mcp run td_mcp_server/server.py

开发

运行测试

bash

运行所有测试

pytest

运行带有覆盖率报告的测试

pytest --cov=td_mcp_server

运行特定模块的测试

pytest tests/unit/test_api.py

代码格式化和检查

bash

使用Ruff进行代码检查

uv run ruff check td_mcp_server tests

使用Ruff格式化代码

uv run ruff format td_mcp_server tests

在所有文件上运行pre-commit钩子

uv run pre-commit run --all-files