Treasure Data MCP-Server

Ein Model Context Protocol (MCP)-Server, der die Treasure Data API-Integration für Claude Code und Claude Desktop bereitstellt und so Datenbankverwaltungs- und Auflistungsfunktionen ermöglicht.

Erste Schritte

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

Authentifizierung

Der Client benötigt zur Authentifizierung einen Treasure Data API-Schlüssel. Sie können diesen auf zwei Arten bereitstellen:

Legen Sie die Umgebungsvariable TD_API_KEY fest:
export TD_API_KEY="your-api-key"
Übergeben Sie es direkt an den Befehl:
python -m td_mcp_server --api-key="your-api-key" list-databases

Verwendung

Befehlszeilenschnittstelle

Das Paket bietet eine einfache Befehlszeilenschnittstelle für allgemeine Vorgänge, die ohne Installation verwendet werden kann:

Datenbanken auflisten

# 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

Abrufen von Informationen zu einer bestimmten Datenbank

# 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

Auflisten von Tabellen in einer Datenbank

# 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

Sie können den Client auch direkt in Ihrem Python-Code verwenden:

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-Endpunkte

Standardmäßig verwendet der Client den Endpunkt der Region USA ( api.treasuredata.com ). Wenn Sie die Region Japan verwenden müssen, geben Sie den Endpunkt an:

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

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

MCP-Serverkonfiguration

Dieser Server implementiert das Model Context Protocol (MCP), um Claude Zugriff auf die Treasure Data API-Funktionalität zu ermöglichen. Er verwendet die FastMCP-Bibliothek mit mcp.run(transport='stdio') -Ansatz für die Standard-MCP-Kommunikation.

Ausführen des MCP-Servers

Sie können den MCP-Server mit der Standard-MCP-CLI ausführen:

# Using MCP CLI
mcp run td_mcp_server/server.py

Der Server benötigt einen Treasure Data API-Schlüssel, der über die Umgebungsvariable TD_API_KEY bereitgestellt werden sollte:

# 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-Implementierung

Dieser Server nutzt die FastMCP -Bibliothek, die ein benutzerfreundliches Framework für den Aufbau von MCP-Servern bietet. Die Implementierung:

Erstellt eine FastMCP-Serverinstanz mit dem Namen „treasure-data“
Verwendet Funktionsdekoratoren ( @mcp.tool() ), um Tools für Datenbankoperationen zu registrieren
Die Tools werden als asynchrone Funktionen mit entsprechenden Typanmerkungen implementiert
Verwendet mcp.run(transport='stdio') , um den Server mit Standard-E/A-Kommunikation zu starten
Verarbeitet MCP-Anfragen und -Antworten automatisch über die FastMCP-Bibliothek

Die Implementierung folgt dem in der Model Context Protocol-Dokumentation für Python-Server empfohlenen Standardmuster und ist daher mit Claude Desktop und anderen MCP-Clients kompatibel.

Einrichten mit Claude Code

So konfigurieren Sie diesen MCP-Server für die Verwendung mit Claude Code:

Klonen Sie das Repository
git clone https://github.com/yourusername/td-mcp-server.git
Legen Sie Ihren Treasure Data API-Schlüssel als Umgebungsvariable fest
export TD_API_KEY="your-api-key"
Fügen Sie den MCP-Server mithilfe der Claude Code CLI hinzu
# 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
Dadurch wird die erforderliche Konfiguration in der Datei .claude/plugins.json Ihres Projekts erstellt oder aktualisiert.
Wenn Sie Claude Code in einem Projekt mit dieser Konfiguration verwenden, haben Sie Zugriff auf die folgenden MCP-Tools:
- mcp__td_list_databases : Listet Datenbanken in Ihrem Treasure Data-Konto auf (standardmäßig nur Namen, fügen Sie verbose=True hinzu, um alle Details zu erhalten, mit den Paginierungsoptionen limit , offset und all_results )
- mcp__td_get_database : Informationen zu einer bestimmten Datenbank abrufen
- mcp__td_list_tables : Listet Tabellen in einer bestimmten Datenbank auf (standardmäßig nur Namen, fügen Sie verbose=True hinzu, um alle Details zu erhalten, mit den Paginierungsoptionen limit , offset und all_results )

Einrichten mit Claude Desktop

So konfigurieren Sie diesen MCP-Server für die Verwendung mit Claude Desktop:

Klonen Sie das Repository
git clone https://github.com/yourusername/td-mcp-server.git
Methode 1: Verwenden der MCP-CLI (empfohlen)
# 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"
Methode 2: Verwenden der Claude Desktop-Benutzeroberfläche
- Gehen Sie zu Einstellungen > MCP-Tools > Neues Tool hinzufügen
- Name: Treasure Data API
- Befehl: mcp run /absolute/path/to/td-mcp-server/td_mcp_server/server.py
- Umgebungsvariablen: Fügen Sie Ihren TD_API_KEY und optional TD_ENDPOINT hinzu
Sie können jetzt die Treasure Data API-Tools in Ihren Claude Desktop-Konversationen verwenden

Verwenden von MCP-Tools in Claude

Nach der Konfiguration können Sie Befehle wie die folgenden verwenden:

# 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

Entwicklung

Umgebungsanforderungen

Dieses Projekt erfordert Python 3.11+ und die folgenden Pakete:

Anfragen >= 2.28.0
pydantic >= 2.0.0
mcp[cli] >= 1.8.1
Klicken Sie auf >= 8.0.0, < 8.2.0
Typer >= 0.9.0

Für Entwicklung und Tests:

pytest >= 7.0.0
pytest-mock >= 3.10.0
pytest-cov >= 4.0.0
Antworten >= 0,23,0
schwarz >= 23.0.0
isort >= 5.12.0
mypy >= 1.0.0
Halskrause >= 0,0,270
Pre-Commit >= 3.3.0

Ausführen von Tests

Dieses Projekt verwendet pytest für Unit-Tests. So führen Sie die Tests aus:

# 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

Mit 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

Die Konfiguration der Pre-Commit-Hooks befindet sich in .pre-commit-config.yaml und umfasst:

Entfernung nachstehender Leerzeichen
Durchsetzung von Zeilenumbrüchen am Dateiende
YAML-Dateivalidierung
Ruff-Fusselung (einschließlich Importsortierung)
Ruff-Formatierung

Typprüfung

Sie können eine statische Typprüfung mit mypy ausführen:

# Install mypy
pip install mypy

# Run type checking
python -m mypy td_mcp_server

Treasure Data MCP Server

Integrations