トレジャーデータMCPサーバー

Claude Code および Claude Desktop に Treasure Data API 統合を提供し、データベース管理とリスト機能を可能にする Model Context Protocol (MCP) サーバー。

はじめる

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

認証

クライアントは認証のためにTreasure Data APIキーを必要とします。これは以下の2つの方法で提供できます。

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)
python -m td_mcp_server.cli_api list

# Show detailed database information
python -m td_mcp_server.cli_api list --verbose

# Get only database names in JSON format
python -m td_mcp_server.cli_api list --format json

# Get detailed database information in JSON format
python -m td_mcp_server.cli_api list --format json --verbose

# Specify a different region endpoint
python -m td_mcp_server.cli_api list --endpoint api.treasuredata.co.jp

# Pagination options (default: limit=30, offset=0)
python -m td_mcp_server.cli_api list --limit 10 --offset 20

# Get all databases regardless of the number
python -m td_mcp_server.cli_api list --all

特定のデータベースに関する情報を取得する

# Get JSON output (default)
python -m td_mcp_server.cli_api get my_database_name

# Get table output
python -m td_mcp_server.cli_api get my_database_name --format table

データベース内のテーブルを一覧表示する

# Show only table names (default, first 30 tables)
python -m td_mcp_server.cli_api tables my_database_name

# Show detailed table information
python -m td_mcp_server.cli_api tables my_database_name --verbose

# Get only table names in JSON format
python -m td_mcp_server.cli_api tables my_database_name --format json

# Get detailed table information in JSON format
python -m td_mcp_server.cli_api tables my_database_name --format json --verbose

# Pagination options (default: limit=30, offset=0)
python -m td_mcp_server.cli_api tables my_database_name --limit 10 --offset 20

# Get all tables regardless of the number
python -m td_mcp_server.cli_api 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機能へのアクセスを提供します。標準的なMCP通信には、FastMCPライブラリを使用しmcp.run(transport='stdio')アプローチを採用しています。

MCPサーバーの実行

標準の MCP CLI を使用して MCP サーバーを実行できます。

# Using MCP CLI
mcp run td_mcp_server/server.py

サーバーには Treasure Data API キーが必要です。これはTD_API_KEY環境変数を介して提供される必要があります。

# Using environment variable
export TD_API_KEY="your-api-key"
mcp run td_mcp_server/server.py

# For Claude Desktop integration, you can include the API key during installation
mcp install td_mcp_server/server.py -v TD_API_KEY="your-api-key" -v TD_ENDPOINT="api.treasuredata.com"

FastMCP実装

このサーバーは、MCPサーバーを構築するための使いやすいフレームワークを提供するFastMCPライブラリを内部的に使用しています。実装は以下のとおりです。

「treasure-data」という名前のFastMCPサーバーインスタンスを作成します。
関数デコレータ( @mcp.tool() )を使用して、データベース操作用のツールを登録します。
ツールは適切な型注釈を持つ非同期関数として実装されています
mcp.run(transport='stdio')を使用して、標準 I/O 通信でサーバーを起動します。
FastMCPライブラリを通じてMCPリクエストとレスポンスを自動的に処理します

この実装は、Python サーバーのモデルコンテキストプロトコルドキュメントで推奨されている標準パターンに従っており、Claude Desktop やその他の MCP クライアントと互換性があります。

Claude Code での設定

この MCP サーバーを Claude Code で使用するように構成するには:

リポジトリをクローンする
git clone https://github.com/yourusername/td-mcp-server.git
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 (use absolute path to server.py) claude mcp add td -e TD_API_KEY=${TD_API_KEY} -e TD_ENDPOINT=api.treasuredata.com -- mcp run /absolute/path/to/td-mcp-server/td_mcp_server/server.py
これにより、プロジェクトの.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 で使用するように構成するには:

リポジトリをクローンする
git clone https://github.com/yourusername/td-mcp-server.git
方法 1: MCP CLI を使用する (推奨)
# Install the server with Claude Desktop using the MCP CLI mcp install /absolute/path/to/td-mcp-server/td_mcp_server/server.py -v TD_API_KEY="your-api-key" -v TD_ENDPOINT="api.treasuredata.com" # For Japan region mcp install /absolute/path/to/td-mcp-server/td_mcp_server/server.py -v TD_API_KEY="your-api-key" -v TD_ENDPOINT="api.treasuredata.co.jp"
方法2: ClaudeデスクトップUIを使用する
- 設定 > MCPツール > 新しいツールの追加に移動します
- 名前: トレジャーデータAPI
- コマンド: mcp run /absolute/path/to/td-mcp-server/td_mcp_server/server.py
- 環境変数: TD_API_KEYとオプションでTD_ENDPOINT追加します
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

発達

環境要件

このプロジェクトには、Python 3.11 以降と次のパッケージが必要です。

リクエスト >= 2.28.0
pydantic >= 2.0.0
mcp[cli] >= 1.8.1
クリック >= 8.0.0、< 8.2.0
タイプ >= 0.9.0

開発とテストの場合:

pytest >= 7.0.0
pytest-mock >= 3.10.0
pytest-cov >= 4.0.0
応答 >= 0.23.0
黒 >= 23.0.0
isort >= 5.12.0
mypy >= 1.0.0
ラフ >= 0.0.270
事前コミット >= 3.3.0

テストの実行

このプロジェクトでは、ユニットテストにpytestを使用しています。テストを実行するには、以下の手順に従ってください。

# Create a virtual environment if you don't have one
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate   # On Windows: .venv\Scripts\activate

# Install required dependencies
pip install pytest pytest-mock pytest-cov responses pytest-asyncio

# Run all tests
python -m pytest

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

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

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

# Run direct MCP integration tests
python -m pytest tests/integration/test_direct_mcp.py

### Test Structure

The tests are organized as follows:

- `tests/unit/test_api.py` - Tests for the Treasure Data API client
- `tests/unit/test_cli_api.py` - Tests for the CLI commands
- `tests/unit/test_mcp_impl.py` - Tests for the MCP tools implementation
- `tests/integration/test_direct_mcp.py` - Integration tests that directly call MCP functions in-process

### Code Formatting, Linting, and Pre-commit Hooks

The project uses Ruff for code formatting and linting, with pre-commit hooks to ensure code quality:

#### Using pip

```bash
# Install development tools
pip install ruff pre-commit mypy

# Run linting with Ruff
python -m ruff check td_mcp_server tests

# Run linting and auto-fix with Ruff
python -m ruff check --fix td_mcp_server tests

# Format code with Ruff
python -m ruff format td_mcp_server tests

# Install pre-commit hooks (do this once)
pre-commit install

# Run all pre-commit hooks on all files
pre-commit run --all-files

UVの使用

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

# Run linting with Ruff
uv run ruff check td_mcp_server tests

# Run linting and auto-fix with Ruff
uv run ruff check --fix td_mcp_server tests

# Format code with Ruff
uv run ruff format td_mcp_server tests

# Install pre-commit hooks (do this once)
uv run pre-commit install

# Run all pre-commit hooks on all files
uv run pre-commit run --all-files

事前コミットフックの構成は.pre-commit-config.yamlにあり、次の内容が含まれます。

末尾の空白の削除
ファイル末尾の改行の強制
YAMLファイルの検証
ラフリント（輸入仕分けを含む）
ラフフォーマット

型チェック

mypy で静的型チェックを実行できます。

# Install mypy
pip install mypy

# Run type checking
python -m mypy td_mcp_server

Treasure Data MCP Server

Integrations