보물 데이터 MCP 서버

Claude Code와 Claude Desktop에 Treasure Data API 통합을 제공하는 MCP(Model Context Protocol) 서버로, 데이터베이스 관리 및 목록 기능이 가능합니다.

시작하기

지엑스피1

입증

클라이언트는 인증을 위해 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)
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

파이썬 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 서버 구성

이 서버는 Claude에게 Treasure Data API 기능에 대한 접근 권한을 제공하기 위해 모델 컨텍스트 프로토콜(MCP)을 구현합니다. 표준 MCP 통신을 위해 mcp.run(transport='stdio') 방식을 사용하는 FastMCP 라이브러리를 사용합니다.

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 설정

Claude Code와 함께 사용하도록 이 MCP 서버를 구성하려면:

저장소를 복제합니다
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 설정

Claude Desktop과 함께 사용하도록 이 MCP 서버를 구성하려면:

저장소를 복제합니다
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 Desktop UI 사용
- 설정 > MCP 도구 > 새 도구 추가로 이동하세요.
- 이름: Treasure Data 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
피단틱 >= 2.0.0
mcp[cli] >= 1.8.1
클릭 >= 8.0.0, < 8.2.0
타이퍼 >= 0.9.0

개발 및 테스트를 위해:

파이테스트 >= 7.0.0
pytest-mock >= 3.10.0
pytest-cov >= 4.0.0
응답 >= 0.23.0
검은색 >= 23.0.0
정렬 >= 5.12.0
마이피 >= 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