Treasure Data MCP Server

Permite a los asistentes de IA consultar e interactuar de forma segura con la plataforma de datos del cliente de Treasure Data.

GitHub
7
Prueba este MCPPatrocinado

Documentación

Treasure Data MCP Server

Servidor MCP (Model Context Protocol) para Treasure Data, que permite a los asistentes de IA consultar e interactuar con Treasure Data a través de una interfaz segura y controlada.

🚀 Vista previa pública

Este servidor MCP se encuentra actualmente en vista previa pública. Estamos emocionados de que lo pruebes y agradecemos tus comentarios para ayudarnos a mejorar el servicio.

Ten en cuenta: Durante este período de vista previa, el uso del servidor es gratuito. Sin embargo, planeamos introducir un modelo de precios basado en el uso en el futuro, que se basará en la cantidad de consultas emitidas. Proporcionaremos un aviso amplio e información detallada sobre los precios antes de implementar cualquier cargo.

Tus comentarios durante esta fase son invaluables y nos ayudarán a dar forma al futuro de esta herramienta. ¡Gracias por ser un adoptante temprano!

Características

  • 🔍 Consulta bases de datos, tablas y esquemas a través de information_schema
  • 📊 Ejecuta consultas SQL con limitación automática de resultados para contextos de LLM
  • 🔒 Diseño centrado en la seguridad con modo de solo lectura por defecto
  • 🌍 Soporte multi-región (regiones US, JP, EU, AP)
  • 🚀 Ejecución sin instalación mediante npx
  • 🎯 Integración con CDP (Customer Data Platform) para la gestión de segmentos y activaciones (Experimental)
  • 🔄 Monitoreo y control de flujos de trabajo: consulta el estado de ejecución, registros y reintenta flujos de trabajo fallidos
  • 📝 Registro de auditoría integral para todas las operaciones

Requisitos previos

Instalación de Node.js

Este servidor MCP requiere Node.js versión 18.0.0 o superior. Si no tienes Node.js instalado:

  1. Descarga Node.js desde nodejs.org

    • Elige la versión LTS (Long Term Support)
    • El instalador incluye npm y npx

  2. Verifica la instalación ejecutando:

node --version  # Should show v18.0.0 or higher
npx --version   # Included with npm 5.2+
  1. Métodos de instalación alternativos:
    • macOS: brew install node (usando Homebrew)
    • Windows: Usa el instalador de nodejs.org o winget install OpenJS.NodeJS
    • Linux: Usa el gestor de paquetes de tu distribución o los repositorios de NodeSource

Instalación

Usando npx (recomendado)

¡No se necesita instalación! Configura tu herramienta MCP para ejecutar @treasuredata/mcp-server directamente mediante npx:

npx @treasuredata/mcp-server

¿Qué es npx? npx es un ejecutor de paquetes que viene con npm 5.2+. Descarga y ejecuta paquetes sin instalarlos globalmente, asegurando que siempre uses la versión más reciente.

Instalación global

Si prefieres una instalación tradicional:

npm install -g @treasuredata/mcp-server

Configuración

Agrega a la configuración de tu cliente MCP (por ejemplo, Claude Desktop):

{
  "mcpServers": {
    "treasuredata": {
      "command": "npx",
      "args": ["@treasuredata/mcp-server"],
      "env": {
        "TD_API_KEY": "your_api_key",
        "TD_SITE": "us01",
        "TD_ENABLE_UPDATES": "false",
        "TD_DATABASE": "sample_datasets"
      }
    }
  }
}

Opciones de configuración

  • TD_API_KEY (obligatorio): Tu clave de API de Treasure Data
  • TD_SITE (opcional): Endpoint de región: us01 (predeterminado), jp01, eu01, ap02, ap03, dev
  • TD_ENABLE_UPDATES (opcional): Habilita operaciones de escritura (herramienta execute): false (predeterminado), true
  • TD_DATABASE (opcional): Base de datos predeterminada para consultas (por ejemplo, sample_datasets)

Integración con Claude Code

Claude Code proporciona soporte integrado para servidores MCP a través del comando claude mcp add. Para usar este servidor MCP con Claude Code:

claude mcp add td -e TD_API_KEY=$TD_API_KEY -- npx @treasuredata/mcp-server

Este comando:

  • Agrega el servidor con el nombre "td"
  • Establece la variable de entorno TD_API_KEY con el valor de tu clave de API
  • Configura Claude Code para usar npx @treasuredata/mcp-server (siempre usa la versión más reciente)

Configuración adicional

También puedes especificar variables de entorno adicionales:

claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=us01 \
  -e TD_DATABASE=sample_datasets \
  -- npx @treasuredata/mcp-server

Una vez configurado, Claude Code tendrá automáticamente acceso a todas las herramientas descritas a continuación para consultar y analizar tu Treasure Data.

Herramientas disponibles

1. list_databases

Lista todas las bases de datos en tu cuenta de Treasure Data.

Ejemplo:

{
  "name": "list_databases",
  "arguments": {}
}

2. list_tables

Lista todas las tablas en una base de datos específica.

Parámetros:

  • database (cadena, opcional): Nombre de la base de datos. Si se omite, usa el contexto de base de datos actual (TD_DATABASE o la última base de datos utilizada)

Ejemplo:

{
  "name": "list_tables",
  "arguments": {
    "database": "sample_datasets"
  }
}

Con base de datos predeterminada configurada:

{
  "name": "list_tables",
  "arguments": {}
}

3. describe_table

Obtén información del esquema de una tabla específica.

Parámetros:

  • database (cadena, opcional): Nombre de la base de datos. Si se omite, usa el contexto de base de datos actual (TD_DATABASE o la última base de datos utilizada)
  • table (cadena, obligatorio): Nombre de la tabla

Ejemplo:

{
  "name": "describe_table",
  "arguments": {
    "database": "sample_datasets",
    "table": "www_access"
  }
}

Con base de datos predeterminada configurada:

{
  "name": "describe_table",
  "arguments": {
    "table": "www_access"
  }
}

4. query

Ejecuta consultas SQL de solo lectura (SELECT, SHOW, DESCRIBE).

Parámetros:

  • sql (cadena, obligatorio): Consulta SQL a ejecutar
  • limit (número, opcional): Máximo de filas (predeterminado: 40, máximo: 10000)

Consejo de rendimiento: Para tablas con una columna time, usa td_interval() o td_time_range() para limitar el rango de tiempo:

  • td_interval(time, '-30d/now') - Últimos 30 días
  • td_interval(time, '-7d/now') - Últimos 7 días
  • td_interval(time, '-1d') - Solo ayer
  • td_interval(time, '-1h/now') - Última hora
  • td_time_range(time, '2024-01-01', '2024-01-31') - Rango de fechas específico

Ejemplo:

{
  "name": "query",
  "arguments": {
    "sql": "SELECT method, COUNT(*) as count FROM www_access GROUP BY method",
    "limit": 10
  }
}

Ejemplo con rango de tiempo:

{
  "name": "query",
  "arguments": {
    "sql": "SELECT method, COUNT(*) as count FROM www_access WHERE td_interval(time, '-7d/now') GROUP BY method",
    "limit": 10
  }
}

5. execute

Ejecuta operaciones de escritura (UPDATE, INSERT, DELETE, etc.): requiere TD_ENABLE_UPDATES=true.

Parámetros:

  • sql (cadena, obligatorio): Sentencia SQL a ejecutar

Ejemplo:

{
  "name": "execute",
  "arguments": {
    "sql": "INSERT INTO events (timestamp, event_type) VALUES (NOW(), 'test')"
  }
}

6. use_database

Cambia el contexto de base de datos actual para consultas posteriores.

Parámetros:

  • database (cadena, obligatorio): Base de datos a la que cambiar

Ejemplo:

{
  "name": "use_database",
  "arguments": {
    "database": "production_logs"
  }
}

Después de cambiar, todas las consultas usarán la nueva base de datos por defecto a menos que se especifique explícitamente.

7. current_database

Obtén el contexto de base de datos actual que se usa para las consultas.

Parámetros: Ninguno

Ejemplo:

{
  "name": "current_database",
  "arguments": {}
}

Respuesta:

{
  "currentDatabase": "sample_datasets",
  "description": "The current database context used for queries"
}

Herramientas CDP (Customer Data Platform) - EXPERIMENTAL

Nota: Las herramientas CDP son actualmente experimentales y pueden no cubrir todos los casos de uso. Se agregarán funcionalidades adicionales según los comentarios de los usuarios.

Las siguientes herramientas están disponibles para interactuar con la Customer Data Platform (CDP) de Treasure Data:

8. list_parent_segments

Lista todos los segmentos principales en tu cuenta de CDP.

Parámetros: Ninguno

Ejemplo:

{
  "name": "list_parent_segments",
  "arguments": {}
}

9. get_parent_segment

Obtén detalles de un segmento principal específico.

Parámetros:

  • parent_segment_id (entero, obligatorio): El ID del segmento principal

Ejemplo:

{
  "name": "get_parent_segment",
  "arguments": {
    "parent_segment_id": 12345
  }
}

10. list_segments

Lista todos los segmentos bajo un segmento principal específico.

Parámetros:

  • parent_segment_id (entero, obligatorio): El ID del segmento principal

Ejemplo:

{
  "name": "list_segments",
  "arguments": {
    "parent_segment_id": 12345
  }
}

11. list_activations

Lista todas las activaciones (sindicaciones) para un segmento específico.

Parámetros:

  • parent_segment_id (entero, obligatorio): El ID del segmento principal
  • segment_id (entero, obligatorio): El ID del segmento

Ejemplo:

{
  "name": "list_activations",
  "arguments": {
    "parent_segment_id": 12345,
    "segment_id": 67890
  }
}

12. get_segment

Obtén información detallada sobre un segmento específico, incluyendo sus reglas y metadatos.

Parámetros:

  • parent_segment_id (entero, obligatorio): El ID del segmento principal
  • segment_id (entero, obligatorio): El ID del segmento

Ejemplo:

{
  "name": "get_segment",
  "arguments": {
    "parent_segment_id": 287197,
    "segment_id": 1536120
  }
}

13. parent_segment_sql

Obtén la sentencia SQL de un segmento principal.

Parámetros:

  • parent_segment_id (entero, obligatorio): El ID del segmento principal

Ejemplo:

{
  "name": "parent_segment_sql",
  "arguments": {
    "parent_segment_id": 287197
  }
}

Ejemplo de respuesta:

select
  a.*
from "cdp_audience_287197"."customers" a

14. segment_sql

Obtén la sentencia SQL de un segmento con condiciones de filtrado aplicadas al segmento principal.

Parámetros:

  • parent_segment_id (entero, obligatorio): El ID del segmento principal
  • segment_id (entero, obligatorio): El ID del segmento

Ejemplo:

{
  "name": "segment_sql",
  "arguments": {
    "parent_segment_id": 287197,
    "segment_id": 1536120
  }
}

Ejemplo de respuesta:

select
  a.*
from "cdp_audience_287197"."customers" a
where (
  (position('Male' in a."gender") > 0)
)

Herramientas de flujo de trabajo (Experimental): monitorea y controla flujos de trabajo Digdag

Nota: Estas herramientas de flujo de trabajo son experimentales y proporcionan acceso detallado a sesiones, intentos y tareas de flujos de trabajo. Están sujetas a cambios en futuras versiones.

Las siguientes herramientas están disponibles para monitorear y controlar flujos de trabajo Digdag. Estas herramientas se integran con el motor de flujos de trabajo de Treasure Data basado en Digdag:

15. list_projects

Lista todos los proyectos de flujo de trabajo.

Parámetros:

  • limit (número, opcional): Máximo de resultados (predeterminado: 100)
  • last_id (cadena, opcional): Cursor de paginación

Ejemplo:

{
  "name": "list_projects",
  "arguments": {
    "limit": 50
  }
}

16. list_workflows

Lista flujos de trabajo, opcionalmente filtrados por nombre de proyecto.

Parámetros:

  • project_name (cadena, opcional): Nombre del proyecto para filtrar
  • limit (número, opcional): Máximo de resultados (predeterminado: 100)
  • last_id (cadena, opcional): Cursor de paginación

Ejemplos:

// List all workflows
{
  "name": "list_workflows",
  "arguments": {
    "limit": 50
  }
}

// List workflows in a specific project
{
  "name": "list_workflows",
  "arguments": {
    "project_name": "my_project",
    "limit": 50
  }
}

17. list_sessions

Lista sesiones de ejecución de flujos de trabajo con opciones de filtrado.

Parámetros:

  • project_name (cadena, opcional): Filtrar por nombre de proyecto
  • workflow_name (cadena, opcional): Filtrar por nombre de flujo de trabajo
  • status (cadena, opcional): Filtrar por estado (running, success, error, killed, planned)
  • from_time (cadena, opcional): Hora de inicio (ISO 8601)
  • to_time (cadena, opcional): Hora de fin (ISO 8601)
  • limit (número, opcional): Máximo de resultados (predeterminado: 100)
  • last_id (cadena, opcional): Cursor de paginación

Ejemplo:

{
  "name": "list_sessions",
  "arguments": {
    "status": "error",
    "from_time": "2024-01-01T00:00:00Z",
    "limit": 20
  }
}

18. get_session_attempts

Obtén todos los intentos de una sesión específica.

Parámetros:

  • session_id (cadena, obligatorio): ID de la sesión

Ejemplo:

{
  "name": "get_session_attempts",
  "arguments": {
    "session_id": "12345"
  }
}

19. get_attempt_tasks

Lista todas las tareas dentro de un intento con su estado de ejecución.

Parámetros:

  • attempt_id (cadena, obligatorio): ID del intento
  • include_subtasks (booleano, opcional): Incluir subtareas (predeterminado: true)

Ejemplo:

{
  "name": "get_attempt_tasks",
  "arguments": {
    "attempt_id": "67890",
    "include_subtasks": false
  }
}

20. get_task_logs

Recupera registros de una tarea específica dentro de un intento.

Parámetros:

  • attempt_id (cadena, obligatorio): ID del intento
  • task_name (cadena, obligatorio): Nombre de la tarea (por ejemplo, "+main+task1")
  • offset (número, opcional): Desplazamiento del registro en bytes
  • limit (número, opcional): Máximo de bytes a recuperar (predeterminado: 1MB)

Ejemplo:

{
  "name": "get_task_logs",
  "arguments": {
    "attempt_id": "67890",
    "task_name": "+main+process_data",
    "limit": 5000
  }
}

21. kill_attempt

Solicita la cancelación de un intento en ejecución.

Parámetros:

  • attempt_id (cadena, obligatorio): ID del intento
  • reason (cadena, opcional): Motivo de la cancelación

Ejemplo:

{
  "name": "kill_attempt",
  "arguments": {
    "attempt_id": "67890",
    "reason": "Stopping for maintenance"
  }
}

22. retry_session

Reintenta una sesión desde el principio o desde una tarea específica.

Parámetros:

  • session_id (cadena, obligatorio): ID de la sesión
  • from_task (cadena, opcional): Nombre de la tarea desde la que reintentar
  • retry_params (objeto, opcional): Parámetros de anulación para el reintento

Ejemplo:

{
  "name": "retry_session",
  "arguments": {
    "session_id": "12345",
    "from_task": "+main+failed_task"
  }
}

23. retry_attempt

Reintenta un intento específico con capacidades de reanudación.

Parámetros:

  • attempt_id (cadena, obligatorio): ID del intento a reintentar
  • resume_from (cadena, opcional): Nombre de la tarea desde la que reanudar (omitir tareas exitosas)
  • retry_params (objeto, opcional): Parámetros de anulación para el reintento
  • force (booleano, opcional): Forzar reintento incluso si el intento está en ejecución (predeterminado: false)

Ejemplo:

{
  "name": "retry_attempt",
  "arguments": {
    "attempt_id": "67890",
    "resume_from": "+main+failed_task",
    "retry_params": {
      "batch_size": 1000
    }
  }
}

Seguridad

  • Solo lectura por defecto: Las operaciones de escritura (herramienta execute) requieren configuración explícita con TD_ENABLE_UPDATES=true
  • Validación de consultas: Todas las consultas se validan antes de la ejecución
  • Registro de auditoría: Todas las operaciones se registran para monitoreo de seguridad
  • Limitación de filas: Inyección automática de LIMIT para consultas SELECT para evitar respuestas grandes
  • Operaciones de control de flujos de trabajo: kill_attempt, retry_session y retry_attempt están habilitadas por defecto ya que son operaciones seguras que no modifican datos directamente

Prompt básico para usar td-mcp-server

Al interactuar con un asistente de IA que tiene td-mcp-server configurado, puedes usar prompts como estos para trabajar eficazmente con tu Treasure Data:

Prompt de configuración inicial

You have access to Treasure Data through the td-mcp-server. You can:
- List databases and tables
- Describe table schemas
- Execute SQL queries on the data
- Switch between databases using use_database
- Check current database context using current_database
- Work with CDP segments and activations (experimental)
- Generate SQL queries for CDP audiences and segments
- Monitor and control Digdag workflows
- View workflow execution status and logs
- Retry failed workflows and attempts

Start by listing available databases to understand what data is available.

Prompts para tareas comunes

Exploración de datos:

Please help me explore the data in Treasure Data:
1. First, list all available databases
2. For the database "sample_datasets", show me all tables
3. Describe the schema of the "www_access" table
4. Show me a sample of 5 rows from this table

Análisis de datos:

Analyze the web access logs in the www_access table:
1. What are the top 10 most accessed URLs?
2. Show the distribution of HTTP methods used
3. Find the busiest hours of the day (use td_interval for recent data)
4. Identify any potential anomalies or interesting patterns

Consultas basadas en tiempo:

For the www_access table, analyze the last 7 days of data:
- Use td_interval(time, '-7d/now') in your WHERE clause
- Show daily traffic trends
- Compare weekday vs weekend patterns
- Identify peak usage times

Análisis de segmentos CDP:

Help me understand my CDP segments:
1. List all parent segments (audiences) available
2. For parent segment ID 287197, show all child segments
3. Get the SQL query that defines this parent segment
4. For segment 1536120, show the SQL with filtering conditions applied
5. Explain what filtering rules are being applied in this segment

Monitoreo de flujos de trabajo:

Help me monitor my Digdag workflows:
1. List all workflow projects available
2. List all workflows in project "my_etl_project"
3. Show me all failed sessions from the last 24 hours
4. For session ID 12345, show all attempts and their status
5. Get the error logs for the failed tasks in attempt 67890
6. Retry the failed session from the task that failed

Solución de problemas de flujos de trabajo:

I have a failed workflow execution. Please help me:
1. List recent error sessions for project "data_pipeline"
2. For the most recent failed session, show me the attempts
3. List all tasks in the failed attempt and identify which ones failed
4. Show me the error logs for the failed tasks
5. Suggest how to retry this workflow

Ejemplos de Uso

Con Claude Desktop

  1. Pídele a Claude que analice tus datos:
Can you show me what databases I have access to in Treasure Data?
  1. Consulta datos específicos:
Show me the top 10 most frequent HTTP methods in the www_access table
  1. Obtén esquemas de tablas:
What columns are in the nasdaq table in sample_datasets?

Conversaciones de Ejemplo

Usuario: "¿Cuál es el número total de registros en la tabla www_access?"

Asistente: Consultaré la tabla www_access para obtener el recuento total de registros.

SELECT COUNT(*) as total_records FROM www_access

[Ejecuta la consulta y devuelve los resultados]

La tabla www_access contiene 5,000 registros en total.

Trabajando con Múltiples Bases de Datos

Usuario: "Necesito trabajar con la base de datos production_logs en lugar de sample_datasets"

Asistente: Cambiaré a la base de datos production_logs por ti.

[Usa la herramienta use_database]

Ahora se cambió a la base de datos production_logs. Todas las consultas posteriores usarán esta base de datos por defecto a menos que especifiques lo contrario.

Ejemplo de Análisis Complejo

Usuario: "¿Puedes analizar los patrones de comportamiento de los usuarios en nuestros registros de acceso del último mes?"

Asistente: Analizaré los patrones de comportamiento de los usuarios a partir de tus registros de acceso. Voy a desglosar esto en varias consultas:

  1. Primero, déjame revisar la estructura de la tabla: [Describe la tabla para entender las columnas disponibles]

  2. Ahora analizaré el patrón general de tráfico del último mes:

SELECT
  DATE(time) as date,
  COUNT(*) as daily_requests,
  COUNT(DISTINCT host) as unique_visitors
FROM www_access
WHERE td_interval(time, '-30d/now')
GROUP BY DATE(time)
ORDER BY date
  1. Déjame identificar las páginas más populares:
SELECT
  path,
  COUNT(*) as visits,
  COUNT(DISTINCT host) as unique_visitors
FROM www_access
WHERE td_interval(time, '-30d/now')
GROUP BY path
ORDER BY visits DESC
LIMIT 20

[Continúa con el análisis y las conclusiones...]

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run integration tests (requires TD_API_KEY_DEVELOPMENT_AWS)
npm run test:integration

# Development mode
npm run dev

Configuraciones de Ejemplo

Consulta el directorio examples/ para ver configuraciones de muestra:

  • claude-desktop-config.json - Configuración básica de Claude Desktop
  • development-config.json - Desarrollo local con registro de actividad
  • multi-region-config.json - Configuración multi-región

Notas para Desarrolladores

Para obtener información sobre cómo probar este servidor MCP con el modo de agente de chat de GitHub Copilot, consulta DEVELOPER_NOTES.md.

Licencia

Licencia Apache 2.0

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee nuestras pautas de contribución y envía solicitudes de extracción a nuestro repositorio.

Soporte

Para problemas y solicitudes de funciones, visita: https://github.com/treasure-data/td-mcp-server/issues