Treasure Data MCP 服务器

模型上下文协议 (MCP) 服务器为 Claude Code 和 Claude Desktop 提供 Treasure Data API 集成，允许数据库管理和列表功能。

安装

# Install from source
git clone https://github.com/yourusername/td-mcp-server.git
cd td-mcp-server
pip install -e .

验证

客户端需要 Treasure Data API 密钥进行身份验证。您可以通过两种方式提供密钥：

设置TD_API_KEY环境变量：
export TD_API_KEY="your-api-key"
直接将其传递给命令：
python -m td_mcp_server --api-key="your-api-key" list-databases

用法

命令行界面

该软件包为常见操作提供了一个简单的命令行界面：

列出数据库

# Show only database names (default, first 30 databases)
uv run td-list-databases

# Show detailed database information
uv run td-list-databases --verbose

# Get only database names in JSON format
uv run td-list-databases --format json

# Get detailed database information in JSON format
uv run td-list-databases --format json --verbose

# Specify a different region endpoint
uv run td-list-databases --endpoint api.treasuredata.co.jp

# Pagination options (default: limit=30, offset=0)
uv run td-list-databases --limit 10 --offset 20

# Get all databases regardless of the number
uv run td-list-databases --all

获取有关特定数据库的信息

# Get JSON output (default)
uv run td-get-database my_database_name

# Get table output
uv run td-get-database my_database_name --format table

列出数据库中的表

# Show only table names (default, first 30 tables)
uv run td-list-tables my_database_name

# Show detailed table information
uv run td-list-tables my_database_name --verbose

# Get only table names in JSON format
uv run td-list-tables my_database_name --format json

# Get detailed table information in JSON format
uv run td-list-tables my_database_name --format json --verbose

# Pagination options (default: limit=30, offset=0)
uv run td-list-tables my_database_name --limit 10 --offset 20

# Get all tables regardless of the number
uv run td-list-tables my_database_name --all

Python API

您还可以在 Python 代码中直接使用客户端：

from td_mcp_server.api import TreasureDataClient

# Initialize client with API key from environment variable
client = TreasureDataClient()

# Or provide API key directly
client = TreasureDataClient(api_key="your-api-key")

# Get databases with pagination (default: first 30 databases)
databases = client.get_databases(limit=30, offset=0)
for db in databases:
    print(f"Database: {db.name}, Tables: {db.count}")

# Get all databases regardless of the number
all_databases = client.get_databases(all_results=True)
for db in all_databases:
    print(f"Database: {db.name}, Tables: {db.count}")

# Get information about a specific database
db = client.get_database("my_database_name")
if db:
    print(f"Found database: {db.name}")
else:
    print("Database not found")

# Get tables in a database with pagination (default: first 30 tables)
tables = client.get_tables("my_database_name", limit=30, offset=0)
for table in tables:
    print(f"Table: {table.name}, Type: {table.type}, Count: {table.count}")

# Get all tables regardless of the number
all_tables = client.get_tables("my_database_name", all_results=True)
for table in all_tables:
    print(f"Table: {table.name}, Type: {table.type}, Count: {table.count}")

API 端点

客户端默认使用美国区域端点（ api.treasuredata.com ），如果需要使用日本区域端点，请指定：

client = TreasureDataClient(endpoint="api.treasuredata.co.jp")

python -m td_mcp_server --endpoint=api.treasuredata.co.jp list-databases

MCP 服务器配置

该服务器实现了模型上下文协议 (MCP)，以便 Claude 访问 Treasure Data API 功能。它使用 FastMCP 库和mcp.run(transport='stdio')方法进行标准 MCP 通信。

运行 MCP 服务器

您可以通过两种方式运行 MCP 服务器：

# Using uv run (recommended)
uv run td-mcp

# Using the installed script (after pip install)
td-mcp

服务器需要 Treasure Data API 密钥，该密钥应通过TD_API_KEY环境变量或--api-key选项提供：

# Using environment variable (recommended)
export TD_API_KEY="your-api-key"
uv run td-mcp

# Or providing the API key directly
uv run td-mcp --api-key="your-api-key"

对于开发或调试，您可以运行带有详细日志记录的服务器：

# Enable verbose logging
uv run td-mcp --verbose

FastMCP 实现

该服务器底层使用了FastMCP库，该库提供了一个易于使用的 MCP 服务器构建框架。具体实现如下：

创建一个名为“treasure-data”的 FastMCP 服务器实例
使用函数装饰器（ @mcp.tool() ）注册数据库操作工具
这些工具以异步函数的形式实现，并带有适当的类型注释
使用mcp.run(transport='stdio')启动具有标准 I/O 通信的服务器
通过 FastMCP 库自动处理 MCP 请求和响应

该实现遵循 Python 服务器的模型上下文协议文档中推荐的标准模式，使其与 Claude Desktop 和其他 MCP 客户端兼容。

使用 Claude Code 进行设置

要配置此 MCP 服务器以与 Claude 代码一起使用：

安装服务器
git clone https://github.com/yourusername/td-mcp-server.git cd td-mcp-server pip install -e .
将您的 Treasure Data API 密钥设置为环境变量
export TD_API_KEY="your-api-key"
使用 Claude Code CLI 添加 MCP 服务器
# Navigate to your project directory cd your-project-directory # Add the MCP server claude mcp add td -e TD_API_KEY=${TD_API_KEY} -e TD_ENDPOINT=api.treasuredata.com -- uv run td-mcp
这将在项目的.claude/plugins.json文件中创建或更新必要的配置。
在具有此配置的项目中使用 Claude Code 时，您将可以访问以下 MCP 工具：
- mcp__td_list_databases ：列出您的 Treasure Data 帐户中的数据库（默认情况下仅显示名称，添加verbose=True可获取完整详细信息，并带有分页选项limit 、 offset和all_results ）
- mcp__td_get_database ：获取有关特定数据库的信息
- mcp__td_list_tables ：列出特定数据库中的表（默认情况下仅显示名称，添加verbose=True可获取完整详细信息，分页选项为limit 、 offset和all_results ）

使用 Claude Desktop 进行设置

要配置此 MCP 服务器以便与 Claude Desktop 一起使用：

按照上述说明安装服务器
方法 1：使用 Claude 桌面 UI
- 前往“设置”>“MCP 工具”>“添加新工具”
- 名称：Treasure Data API
- 命令： uv run td-mcp
- 环境变量：添加您的TD_API_KEY
方法二：使用claude_desktop_config.json（推荐）
- 创建或更新您的 claude_desktop_config.json 文件：
  - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  - Windows： %APPDATA%\Claude\claude_desktop_config.json
- 添加以下配置：
  { "mcpServers": { "treasure-data": { "command": "uv", "args": ["run", "td-mcp"], "env": { "TD_API_KEY": "your-api-key" } } } }
- 将your-api-key替换为你的实际 Treasure Data API 密钥
保存配置并重新启动Claude Desktop
您现在可以在 Claude Desktop 对话中使用 Treasure Data API 工具

在 Claude 中使用 MCP 工具

配置完成后，您可以使用以下命令：

# Get only database names (default, first 30 databases)
/mcp td_list_databases

# Get full database details
/mcp td_list_databases verbose=True

# Pagination options (default: limit=30, offset=0)
/mcp td_list_databases limit=10 offset=20

# Get all databases regardless of the number
/mcp td_list_databases all_results=True

# Get information about a specific database
/mcp td_get_database my_database_name

# Get only table names in a database (default, first 30 tables)
/mcp td_list_tables database_name=my_database_name

# Get detailed information about tables in a database
/mcp td_list_tables database_name=my_database_name verbose=True

# Pagination options (default: limit=30, offset=0)
/mcp td_list_tables database_name=my_database_name limit=10 offset=20

# Get all tables regardless of the number
/mcp td_list_tables database_name=my_database_name all_results=True

发展

设置开发环境

# Clone the repository
git clone https://github.com/yourusername/td-mcp-server.git
cd td-mcp-server

# Install dev dependencies
pip install -e ".[dev]"

运行测试

该项目使用 pytest 进行单元测试。运行测试的步骤如下：

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=td_mcp_server

# Run tests for a specific module
pytest tests/unit/test_api.py

# Run a specific test
pytest tests/unit/test_api.py::TestTreasureDataClient::test_get_databases

测试结构

测试安排如下：

tests/unit/test_api.py - Treasure Data API 客户端测试
tests/unit/test_cli_api.py - CLI 命令测试
tests/unit/test_mcp_impl.py - MCP 工具实现的测试

代码格式化

该项目使用Black和isort进行代码格式化：

# Format code with Black
black td_mcp_server tests

# Sort imports with isort
isort td_mcp_server tests

类型检查

您可以使用 mypy 运行静态类型检查：

mypy td_mcp_server

Treasure Data MCP Server

Integrations