Servidor MCP de Treasure Data
Un servidor de Protocolo de contexto de modelo (MCP) que proporciona integración de API de Treasure Data para Claude Code y Claude Desktop, lo que permite la gestión de bases de datos y la funcionalidad de listado.
Empezando
# Clone the repository
git clone https://github.com/yourusername/td-mcp-server.git
cd td-mcp-server
Autenticación
El cliente necesita una clave API de Treasure Data para la autenticación. Puede proporcionarla de dos maneras:
- Establezca la variable de entorno
TD_API_KEY :export TD_API_KEY="your-api-key"
- Pásalo directamente al comando:
python -m td_mcp_server --api-key="your-api-key" list-databases
Uso
Interfaz de línea de comandos
El paquete proporciona una interfaz de línea de comandos sencilla para operaciones comunes que se pueden utilizar sin instalación:
Lista de bases de datos
# 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
Listar tablas en una base de datos
# 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 de Python
También puedes utilizar el cliente directamente en tu código 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}")
Puntos finales de API
De forma predeterminada, el cliente utiliza el punto de conexión de la región de EE. UU. ( api.treasuredata.com ). Si necesita usar la región de Japón, especifique el punto de conexión:
client = TreasureDataClient(endpoint="api.treasuredata.co.jp")
python -m td_mcp_server --endpoint=api.treasuredata.co.jp list-databases
Configuración del servidor MCP
Este servidor implementa el Protocolo de Contexto de Modelo (MCP) para proporcionar a Claude acceso a la API de Datos de Treasure. Utiliza la biblioteca FastMCP con el método mcp.run(transport='stdio') para la comunicación MCP estándar.
Ejecución del servidor MCP
Puede ejecutar el servidor MCP utilizando la CLI MCP estándar:
# Using MCP CLI
mcp run td_mcp_server/server.py
El servidor requiere una clave API de Treasure Data, que debe proporcionarse a través de la variable de entorno 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"
Implementación de FastMCP
En esencia, este servidor utiliza la biblioteca FastMCP , que proporciona un marco fácil de usar para crear servidores MCP. La implementación:
- Crea una instancia de servidor FastMCP con el nombre "treasure-data"
- Utiliza decoradores de funciones (
@mcp.tool() ) para registrar herramientas para operaciones de base de datos - Las herramientas se implementan como funciones asincrónicas con anotaciones de tipo adecuadas.
- Utiliza
mcp.run(transport='stdio') para iniciar el servidor con comunicación de E/S estándar - Maneja solicitudes y respuestas de MCP automáticamente a través de la biblioteca FastMCP
La implementación sigue el patrón estándar recomendado en la documentación del Protocolo de Contexto de Modelo para servidores Python, lo que lo hace compatible con Claude Desktop y otros clientes MCP.
Configuración con Claude Code
Para configurar este servidor MCP para su uso con Claude Code:
- Clonar el repositorio
git clone https://github.com/yourusername/td-mcp-server.git
- Establezca su clave API de Treasure Data como una variable de entorno
export TD_API_KEY="your-api-key"
- Agregue el servidor MCP usando la CLI de Claude Code
# 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 de su proyecto. - Al utilizar Claude Code en un proyecto con esta configuración, tendrá acceso a las siguientes herramientas MCP:
mcp__td_list_databases : enumera las bases de datos en su cuenta de Treasure Data (solo nombres de manera predeterminada, agregue verbose=True para obtener detalles completos, con opciones de paginación limit , offset y all_results )mcp__td_get_database : Obtener información sobre una base de datos específicamcp__td_list_tables : enumera las tablas en una base de datos específica (solo nombres de manera predeterminada, agregue verbose=True para obtener detalles completos, con opciones de paginación limit , offset y all_results )
Configuración con Claude Desktop
Para configurar este servidor MCP para su uso con Claude Desktop:
- Clonar el repositorio
git clone https://github.com/yourusername/td-mcp-server.git
- Método 1: Uso de la CLI de MCP (recomendado)
# 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"
- Método 2: Uso de la interfaz de usuario de Claude Desktop
- Vaya a Configuración > Herramientas MCP > Agregar nueva herramienta
- Nombre: API de datos del tesoro
- Comando:
mcp run /absolute/path/to/td-mcp-server/td_mcp_server/server.py - Variables de entorno: agregue su
TD_API_KEY y opcionalmente TD_ENDPOINT
- Ahora puedes usar las herramientas de la API de Treasure Data en tus conversaciones de Claude Desktop
Uso de herramientas MCP en Claude
Una vez configurado, puedes utilizar comandos como:
# 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
Desarrollo
Requisitos ambientales
Este proyecto requiere Python 3.11+ y los siguientes paquetes:
- solicitudes >= 2.28.0
- pydantic >= 2.0.0
- mcp[cli] >= 1.8.1
- haga clic >= 8.0.0, < 8.2.0
- mecanógrafo >= 0.9.0
Para desarrollo y pruebas:
- pytest >= 7.0.0
- pytest-mock >= 3.10.0
- pytest-cov >= 4.0.0
- respuestas >= 0.23.0
- negro >= 23.0.0
- isort >= 5.12.0
- mypy >= 1.0.0
- gorguera >= 0.0.270
- pre-commit >= 3.3.0
Ejecución de pruebas
Este proyecto utiliza PyTest para pruebas unitarias. Para ejecutar las pruebas:
# 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
Usando 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
La configuración de los ganchos previos a la confirmación está en .pre-commit-config.yaml e incluye:
- Eliminación de espacios en blanco finales
- Aplicación de nueva línea al final del archivo
- Validación de archivos YAML
- Eliminación de pelusas (incluye clasificación de importación)
- Formato Ruff
Comprobación de tipos
Puede ejecutar la comprobación de tipo estático con mypy:
# Install mypy
pip install mypy
# Run type checking
python -m mypy td_mcp_server