Treasure Data MCP Server

MCP (Model Context Protocol) server for Treasure Data, enabling AI assistants to query and interact with Treasure Data through a secure, controlled interface.

🚀 Public Preview

This MCP server is currently in a public preview. We're excited for you to try it out and welcome your feedback to help us improve the service.

Please note: During this preview period, use of the server is free. However, we plan to introduce a usage-based pricing model in the future, which will be based on the number of queries issued. We will provide ample notice and detailed pricing information before any charges are implemented.

Your feedback during this phase is invaluable and will help us shape the future of this tool. Thank you for being an early adopter!

Features

- 🔍 Query databases, tables, and schemas through information_schema
- 📊 Execute SQL queries with automatic result limiting for LLM contexts
- 🔒 Security-first design with read-only mode by default
- 🌍 Multi-site support (US, JP, EU, AP regions)
- 🚀 Zero-install execution via npx
- 🎯 CDP (Customer Data Platform) integration for segment and activation management (Experimental)
- 🔄 Workflow monitoring and control - view execution status, logs, and retry failed workflows
- 📝 Comprehensive audit logging for all operations

Prerequisites

$3

This MCP server requires Node.js version 18.0.0 or higher. If you don't have Node.js installed:

1. Download Node.js from nodejs.org
- Choose the LTS (Long Term Support) version
- The installer includes npm and npx

2. Verify installation by running:
``bash
node --version # Should show v18.0.0 or higher
npx --version # Included with npm 5.2+
`

3. Alternative installation methods:
- macOS: brew install node (using Homebrew)
- Windows: Use the installer from nodejs.org or winget install OpenJS.NodeJS
- Linux: Use your distribution's package manager or NodeSource repositories

Installation

$3

No installation needed! Configure your MCP tool to run @treasuredata/mcp-server directly via npx:

`bash
npx @treasuredata/mcp-server
`

> What is npx? npx is a package runner that comes with npm 5.2+. It downloads and runs packages without installing them globally, ensuring you always use the latest version.

$3

If you prefer a traditional installation:

`bash
npm install -g @treasuredata/mcp-server
`

Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

`json
{
"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"
}
}
}
}
`

$3

- TD_API_KEY (required): Your Treasure Data API key
- TD_SITE (optional): Region endpoint - us01 (default), jp01, eu01, ap02, ap03, dev
- TD_ENABLE_UPDATES (optional): Enable write operations (execute tool) - false (default), true
- TD_DATABASE (optional): Default database for queries (e.g., sample_datasets)

Claude Code Integration

Claude Code provides built-in support for MCP servers through the claude mcp add command. To use this MCP server with Claude Code:

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

This command:
- Adds the server with the name "td"
- Sets the TD_API_KEY environment variable to your API key value
- Configures Claude Code to use npx @treasuredata/mcp-server (always uses latest version)

$3

You can also specify additional environment variables:

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

Once configured, Claude Code will automatically have access to all the tools described below for querying and analyzing your Treasure Data.

Available Tools

$3

List all databases in your Treasure Data account.

Example:
`json
{
"name": "list_databases",
"arguments": {}
}
`

$3

List all tables in a specific database.

Parameters:
- database (string, optional): Database name. If omitted, uses the current database context (TD_DATABASE or last used database)

Example:
`json
{
"name": "list_tables",
"arguments": {
"database": "sample_datasets"
}
}
`

With default database configured:
`json
{
"name": "list_tables",
"arguments": {}
}
`

$3

Get schema information for a specific table.

Parameters:
- database (string, optional): Database name. If omitted, uses the current database context (TD_DATABASE or last used database)
- table (string, required): Table name

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

With default database configured:
`json
{
"name": "describe_table",
"arguments": {
"table": "www_access"
}
}
`

$3

Execute read-only SQL queries (SELECT, SHOW, DESCRIBE).

Parameters:
- sql (string, required): SQL query to execute
- limit (number, optional): Max rows (default: 40, max: 10000)

Performance Tip: For tables with a time column, use td_interval() or td_time_range() to limit the time range:
- td_interval(time, '-30d/now') - Last 30 days
- td_interval(time, '-7d/now') - Last 7 days
- td_interval(time, '-1d') - Yesterday only
- td_interval(time, '-1h/now') - Last hour
- td_time_range(time, '2024-01-01', '2024-01-31') - Specific date range

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

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

$3


Execute write operations (UPDATE, INSERT, DELETE, etc.) - requires TD_ENABLE_UPDATES=true.

Parameters:
- sql (string, required): SQL statement to execute

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

$3

Switch the current database context for subsequent queries.

Parameters:
- database (string, required): Database to switch to

Example:
`json
{
"name": "use_database",
"arguments": {
"database": "production_logs"
}
}
`

After switching, all queries will use the new database by default unless explicitly specified.

$3

Get the current database context being used for queries.

Parameters:
None

Example:
`json
{
"name": "current_database",
"arguments": {}
}
`

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

$3

Note: CDP tools are currently experimental and may not cover all use cases. Additional functionality will be added based on user feedback.

The following tools are available for interacting with Treasure Data's Customer Data Platform (CDP):

$3

List all parent segments in your CDP account.

Parameters:
None

Example:
`json
{
"name": "list_parent_segments",
"arguments": {}
}
`

$3

Get details of a specific parent segment.

Parameters:
- parent_segment_id (integer, required): The ID of the parent segment

Example:
`json
{
"name": "get_parent_segment",
"arguments": {
"parent_segment_id": 12345
}
}
`

$3

List all segments under a specific parent segment.

Parameters:
- parent_segment_id (integer, required): The ID of the parent segment

Example:
`json
{
"name": "list_segments",
"arguments": {
"parent_segment_id": 12345
}
}
`

$3

List all activations (syndications) for a specific segment.

Parameters:
- parent_segment_id (integer, required): The ID of the parent segment
- segment_id (integer, required): The ID of the segment

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

$3

Get detailed information about a specific segment, including its rules and metadata.

Parameters:
- parent_segment_id (integer, required): The parent segment ID
- segment_id (integer, required): The segment ID

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

$3

Get the SQL statement for a parent segment.

Parameters:
- parent_segment_id (integer, required): The parent segment ID

Example:
`json
{
"name": "parent_segment_sql",
"arguments": {
"parent_segment_id": 287197
}
}
`

Response Example:
`sql
select
a.*
from "cdp_audience_287197"."customers" a
`

$3

Get the SQL statement for a segment with filtering conditions applied to the parent segment.

Parameters:
- parent_segment_id (integer, required): The parent segment ID
- segment_id (integer, required): The segment ID

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

Response Example:
`sql
select
a.*
from "cdp_audience_287197"."customers" a
where (
(position('Male' in a."gender") > 0)
)
`

$3

> Note: These workflow tools are experimental and provide detailed access to workflow sessions, attempts, and tasks. They are subject to change in future releases.

The following tools are available for monitoring and controlling Digdag workflows. These tools integrate with Treasure Data's workflow engine based on Digdag:

$3

List all workflow projects.

Parameters:
- limit (number, optional): Maximum results (default: 100)
- last_id (string, optional): Pagination cursor

Example:
`json
{
"name": "list_projects",
"arguments": {
"limit": 50
}
}
`

$3

List workflows, optionally filtered by project name.

Parameters:
- project_name (string, optional): Project name to filter by
- limit (number, optional): Maximum results (default: 100)
- last_id (string, optional): Pagination cursor

Examples:
`json
// 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
}
}
`

$3

List workflow execution sessions with filtering options.

Parameters:
- project_name (string, optional): Filter by project name
- workflow_name (string, optional): Filter by workflow name
- status (string, optional): Filter by status (running, success, error, killed, planned)
- from_time (string, optional): Start time (ISO 8601)
- to_time (string, optional): End time (ISO 8601)
- limit (number, optional): Maximum results (default: 100)
- last_id (string, optional): Pagination cursor

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

$3

Get all attempts for a specific session.

Parameters:
- session_id (string, required): Session ID

Example:
`json
{
"name": "get_session_attempts",
"arguments": {
"session_id": "12345"
}
}
`

$3

List all tasks within an attempt with their execution status.

Parameters:
- attempt_id (string, required): Attempt ID
- include_subtasks (boolean, optional): Include subtasks (default: true)

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

$3

Retrieve logs for a specific task within an attempt.

Parameters:
- attempt_id (string, required): Attempt ID
- task_name (string, required): Task name (e.g., "+main+task1")
- offset (number, optional): Log offset in bytes
- limit (number, optional): Maximum bytes to retrieve (default: 1MB)

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

$3

Request cancellation of a running attempt.

Parameters:
- attempt_id (string, required): Attempt ID
- reason (string, optional): Reason for cancellation

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

$3

Retry a session from the beginning or a specific task.

Parameters:
- session_id (string, required): Session ID
- from_task (string, optional): Task name to retry from
- retry_params (object, optional): Override parameters for retry

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

$3

Retry a specific attempt with resume capabilities.

Parameters:
- attempt_id (string, required): Attempt ID to retry
- resume_from (string, optional): Task name to resume from (skip successful tasks)
- retry_params (object, optional): Override parameters for retry
- force (boolean, optional): Force retry even if attempt is running (default: false)

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

Security

- Read-only by default: Write operations (execute tool) require explicit configuration with TD_ENABLE_UPDATES=true
- Query validation: All queries are validated before execution
- Audit logging: All operations are logged for security monitoring
- Row limiting: Automatic LIMIT injection for SELECT queries to prevent large responses
- Workflow control operations: kill_attempt, retry_session, and retry_attempt are enabled by default as they are safe operations that don't modify data directly

Basic Prompt for Using td-mcp-server

When interacting with an AI assistant that has td-mcp-server configured, you can use prompts like these to effectively work with your Treasure Data:

$3


`
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.
`

$3

Data Exploration:
`
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
`

Data Analysis:
`
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
`

Time-based Queries:
`
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
`

CDP Segment Analysis:
`
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
`

Workflow Monitoring:
`
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
`

Workflow Troubleshooting:
`
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
`

Usage Examples

$3

1. Ask Claude to analyze your data:
`
Can you show me what databases I have access to in Treasure Data?
`

2. Query specific data:
`
Show me the top 10 most frequent HTTP methods in the www_access table
`

3. Get table schemas:
`
What columns are in the nasdaq table in sample_datasets?
`

$3

User: "What's the total number of records in the www_access table?"

Assistant: I'll query the www_access table to get the total record count.

`sql
SELECT COUNT(*) as total_records FROM www_access
`

[Executes query and returns results]

The www_access table contains 5,000 total records.

$3

User: "I need to work with the production_logs database instead of sample_datasets"

Assistant: I'll switch to the production_logs database for you.

[Uses use_database tool]

Now switched to production_logs database. All subsequent queries will use this database by default unless you specify otherwise.

$3

User: "Can you analyze user behavior patterns in our access logs for the past month?"

Assistant: I'll analyze the user behavior patterns from your access logs. Let me break this down into several queries:

1. First, let me check the table structure:
[Describes table to understand available columns]

2. Now I'll analyze the overall traffic pattern for the past month:
`sql
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
`

3. Let me identify the most popular pages:
`sql
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
`

[Continues with analysis and insights...]

Development

`bash


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
`

$3

See the examples/ directory for sample configurations:
- claude-desktop-config.json - Basic Claude Desktop setup
- development-config.json - Local development with logging
- multi-region-config.json` - Multi-region setup

Developer Notes

For information on testing this MCP server with GitHub Copilot Chat agent mode, see DEVELOPER_NOTES.md.

License

Apache License 2.0

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support

For issues and feature requests, please visit: https://github.com/treasure-data/td-mcp-server/issues