name	td-mcp
description	Expert assistance for connecting Claude Code to Treasure Data via MCP (Model Context Protocol) server. Use this skill when users need help setting up TD MCP integration, using MCP tools to query TD, managing databases and tables through MCP, or troubleshooting MCP connections.

Treasure Data MCP Server

Expert assistance for integrating Treasure Data with Claude Code using the Model Context Protocol (MCP) server.

When to Use This Skill

Use this skill when:

Setting up Claude Code to access Treasure Data via MCP
Configuring TD MCP server for the first time
Using MCP tools to query TD databases and tables
Exploring TD data through Claude Code's natural language interface
Managing TD workflows and CDP segments via MCP
Troubleshooting MCP connection or authentication issues
Understanding available MCP tools and their usage
Switching between TD regions (US, JP, EU, AP)

What is TD MCP Server?

The Treasure Data MCP (Model Context Protocol) server enables Claude Code and other AI assistants to interact with Treasure Data through a secure, controlled interface. It provides:

Direct TD Access: Query databases, tables, and execute SQL from Claude Code
Read-Only by Default: Secure access with optional write operations
Multi-Region Support: Works with all TD deployment regions
Natural Language Queries: Ask questions about your data in plain English
Workflow Management: Monitor and control TD workflows
CDP Integration: Manage customer segments and activations

Status: Public preview (free during preview, usage-based pricing planned)

Core Principles

1. Installation

Prerequisites:

Node.js 18.0.0 or higher
TD API key with appropriate permissions
Claude Code installed

Check Node.js Version:

node --version  # Should show v18.0.0 or higher

Install Node.js if needed:

# macOS (Homebrew)
brew install node

# Windows (winget)
winget install OpenJS.NodeJS

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

No Installation Required: The MCP server runs via npx, so no global installation is needed. However, you can optionally install globally:

npm install -g @treasuredata/mcp-server

2. Setup with Claude Code

Quick Setup:

# Set your TD API key
export TD_API_KEY="your_api_key_here"

# Add TD MCP server to Claude Code
claude mcp add td -e TD_API_KEY=$TD_API_KEY -- npx @treasuredata/mcp-server

With Custom Configuration:

# US region with default database
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=us01 \
  -e TD_DATABASE=sample_datasets \
  -- npx @treasuredata/mcp-server

# Tokyo region
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=jp01 \
  -- npx @treasuredata/mcp-server

# EU region
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=eu01 \
  -- npx @treasuredata/mcp-server

Enable Write Operations (Optional):

# Enable INSERT, UPDATE, DELETE, CREATE, DROP operations
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_ENABLE_UPDATES=true \
  -- npx @treasuredata/mcp-server

Verify Installation:

# List installed MCP servers
claude mcp list

# Should show 'td' in the list

3. Configuration Options

Environment Variables:

Variable	Required	Default	Description
`TD_API_KEY`	Yes	-	Your Treasure Data API key
`TD_SITE`	No	`us01`	TD region: us01, jp01, eu01, ap02, ap03
`TD_DATABASE`	No	-	Default database for queries
`TD_ENABLE_UPDATES`	No	`false`	Enable write operations

Regional Endpoints:

us01 - United States (default)
jp01 - Tokyo, Japan
eu01 - European Union
ap02 - Asia Pacific (Seoul)
ap03 - Asia Pacific (Tokyo alternate)

4. Using MCP Tools in Claude Code

Once configured, you can use natural language to interact with TD:

Example Queries:

"Show me all databases in my TD account"
"List tables in the sample_datasets database"
"What's the schema of the nasdaq table?"
"Query the top 10 symbols by count from nasdaq table"
"Show me yesterday's events from the user_events table"

Claude Code will automatically use the appropriate MCP tools to fulfill your requests.

Available MCP Tools

Data Exploration Tools

1. list_databases

Lists all databases in your TD account.

Usage in Claude Code:

"List all my TD databases"
"Show me what databases I have"

Direct Tool Call:

{
  "tool": "list_databases"
}

2. list_tables

Lists tables in a database.

Usage in Claude Code:

"List tables in sample_datasets"
"What tables are in my analytics database?"

Direct Tool Call:

{
  "tool": "list_tables",
  "database": "sample_datasets"
}

3. describe_table

Shows schema information for a specific table.

Usage in Claude Code:

"Describe the nasdaq table"
"What columns does user_events have?"
"Show me the schema of the transactions table"

Direct Tool Call:

{
  "tool": "describe_table",
  "database": "sample_datasets",
  "table": "nasdaq"
}

4. current_database

Shows the current database context.

Usage in Claude Code:

"What database am I currently using?"
"Show current database"

5. use_database

Switches the database context for subsequent queries.

Usage in Claude Code:

"Switch to the analytics database"
"Use the sample_datasets database"

Direct Tool Call:

{
  "tool": "use_database",
  "database": "analytics"
}

Query Execution Tools

6. query (Read-Only)

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

Features:

Default limit: 40 rows (optimized for LLM context)
Configurable up to 10,000 rows
Automatic timeout handling
Safe for production use

Usage in Claude Code:

"Query the nasdaq table and show me the top 10 symbols"
"SELECT COUNT(*) FROM user_events WHERE TD_INTERVAL(time, '-1d')"
"Show me yesterday's revenue from transactions"

Direct Tool Call:

{
  "tool": "query",
  "sql": "SELECT symbol, COUNT(*) as cnt FROM nasdaq GROUP BY symbol ORDER BY cnt DESC LIMIT 10"
}

With Custom Row Limit:

{
  "tool": "query",
  "sql": "SELECT * FROM large_table LIMIT 100",
  "max_rows": 100
}

7. execute (Write Operations)

Executes write operations (INSERT, UPDATE, DELETE, CREATE, DROP).

Requirements:

Must set TD_ENABLE_UPDATES=true
Use with caution in production

Usage in Claude Code:

"Create a table called test_table with columns id and name"
"Insert a test row into test_table"

Direct Tool Call:

{
  "tool": "execute",
  "sql": "CREATE TABLE test_table (id INT, name VARCHAR)"
}

CDP Tools (Experimental)

8. list_parent_segments

Lists all parent segments in CDP.

Usage in Claude Code:

"List all parent segments"
"Show me my CDP parent segments"

9. get_parent_segment

Gets details of a specific parent segment.

Usage in Claude Code:

"Get details for parent segment 12345"

10. list_segments

Lists segments under a parent segment.

Usage in Claude Code:

"List segments in parent segment 12345"

11. list_activations

Lists syndications/activations for a segment.

Usage in Claude Code:

"Show activations for segment 67890"

12. get_segment

Returns segment details including rules.

Usage in Claude Code:

"Get segment 67890 details"

13. parent_segment_sql

Retrieves parent segment SQL statement.

Usage in Claude Code:

"Show SQL for parent segment 12345"

14. segment_sql

Gets segment SQL with filtering conditions.

Usage in Claude Code:

"Show SQL for segment 67890"

Workflow Tools (Experimental)

15. list_projects

Lists workflow projects with pagination.

Usage in Claude Code:

"List all workflow projects"
"Show me my digdag projects"

16. list_workflows

Lists workflows, optionally filtered by project.

Usage in Claude Code:

"List workflows in project my_project"
"Show all workflows"

17. list_sessions

Lists execution sessions with status and time filtering.

Usage in Claude Code:

"Show recent workflow sessions"
"List failed workflow executions"

Common Patterns

Pattern 1: Initial Setup and Data Exploration

# Step 1: Install and configure TD MCP
export TD_API_KEY="your_api_key"
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=us01 \
  -- npx @treasuredata/mcp-server

# Step 2: Start Claude Code
claude

# Step 3: Explore your data (in Claude Code conversation)

In Claude Code:

> List all my TD databases

> Switch to sample_datasets database

> List tables in this database

> Describe the nasdaq table

> Query: SELECT symbol, COUNT(*) as cnt FROM nasdaq
  GROUP BY symbol ORDER BY cnt DESC LIMIT 10

Explanation: This pattern establishes MCP connection and progressively explores TD data structure using natural language.

Pattern 2: Time-Series Data Analysis

In Claude Code:

> Switch to the analytics database

> Query yesterday's events:
  SELECT
    event_name,
    COUNT(*) as event_count,
    COUNT(DISTINCT user_id) as unique_users
  FROM user_events
  WHERE TD_INTERVAL(time, '-1d', 'JST')
  GROUP BY event_name
  ORDER BY event_count DESC

> Now show me the last 7 days trend:
  SELECT
    TD_TIME_FORMAT(time, 'yyyy-MM-dd', 'JST') as date,
    COUNT(*) as daily_events
  FROM user_events
  WHERE TD_INTERVAL(time, '-7d', 'JST')
  GROUP BY 1
  ORDER BY 1

> What's the hourly pattern for today?
  SELECT
    TD_TIME_FORMAT(time, 'HH', 'JST') as hour,
    COUNT(*) as event_count
  FROM user_events
  WHERE TD_INTERVAL(time, '0d', 'JST')
  GROUP BY 1
  ORDER BY 1

Explanation: Uses TD_INTERVAL for efficient time-based queries. MCP automatically limits results for optimal LLM context.

Pattern 3: Multi-Database Analysis

In Claude Code:

> Switch to sales database

> What's the total revenue from yesterday?
  SELECT SUM(amount) as total_revenue
  FROM transactions
  WHERE TD_INTERVAL(time, '-1d', 'JST')

> Now switch to marketing database

> How many new users signed up yesterday?
  SELECT COUNT(DISTINCT user_id) as new_users
  FROM user_signups
  WHERE TD_INTERVAL(time, '-1d', 'JST')

> Can you join data from both databases to calculate
  revenue per new user?

Explanation: Demonstrates switching between databases and combining insights from multiple data sources.

Pattern 4: Schema Discovery and Documentation

In Claude Code:

> List all tables in the production database

> For each table, show me:
  1. The table schema
  2. Row count
  3. Sample of first 5 rows

> Can you create a markdown document describing
  all tables and their relationships?

> Which tables have a 'user_id' column?

Explanation: Uses MCP tools to automatically document database schema and relationships.

Pattern 5: Workflow Monitoring

In Claude Code:

> List all workflow projects

> Show workflows in the etl_pipeline project

> List recent workflow sessions for the daily_aggregation workflow

> Are there any failed workflow executions in the last 24 hours?

> Show me the details of the most recent failed session

Explanation: Monitors TD workflows through MCP, useful for debugging and operational awareness.

Best Practices

Use Read-Only Mode by Default
- Keep TD_ENABLE_UPDATES=false for safety
- Only enable write operations when necessary
- Create separate MCP connections for read and write if needed

Leverage TD Time Functions

-- Good: Uses partition pruning
WHERE TD_INTERVAL(time, '-1d', 'JST')

-- Avoid: Scans entire table
WHERE date = '2024-01-01'

Be Mindful of Result Sizes
- Default 40 rows is optimized for LLM context
- Use aggregations instead of raw data when possible
- Add explicit LIMIT clauses for large tables

Set Default Database

# Reduces need to specify database repeatedly
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_DATABASE=your_main_database \
  -- npx @treasuredata/mcp-server

Use Natural Language
- MCP works best with conversational queries
- You can refine queries through dialogue
- Claude Code understands context from previous messages
Regional Configuration
- Always set TD_SITE to match your data location
- Reduces latency and ensures data residency compliance

Secure API Key Management

# Store in environment variable
export TD_API_KEY="your_api_key"

# Or use shell config
echo 'export TD_API_KEY="your_api_key"' >> ~/.bashrc

Test Queries Interactively
- Use Claude Code to test and refine queries
- Once optimized, save to scripts or workflows
Use Descriptive Names
- When adding MCP server, use descriptive names
- Example: claude mcp add td-production vs td-staging
Monitor Usage
- MCP is free during preview
- Track your usage patterns for future planning

Common Issues and Solutions

Issue: Node.js Version Too Old

Symptoms:

Error: "Node.js version 18.0.0 or higher required"
MCP server fails to start

Solutions:

# Check current version
node --version

# Update Node.js (macOS)
brew upgrade node

# Update Node.js (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version  # Should show v18.0.0+

Issue: Authentication Failed

Symptoms:

"Authentication error"
"Invalid API key"
"403 Forbidden"

Solutions:

Verify API Key Format

echo $TD_API_KEY
# Should display your API key

Check API Key Permissions
- Log in to TD console
- Verify key has appropriate permissions
- Regenerate if necessary

Verify Regional Endpoint

# Ensure TD_SITE matches your account region
claude mcp remove td
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=jp01 \
  -- npx @treasuredata/mcp-server

Test API Key with curl

curl -H "Authorization: TD1 $TD_API_KEY" \
     https://api.treasuredata.com/v3/database/list

Issue: MCP Server Not Found

Symptoms:

"td: command not found"
Claude Code doesn't see TD tools

Solutions:

Verify MCP Installation

claude mcp list
# Should show 'td' in output

Re-add MCP Server

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

Check npx is Available
```
which npx
# Should show path to npx
```
Restart Claude Code
```
# Exit and restart Claude Code
```

Issue: Query Timeout

Symptoms:

Query runs but never completes
Timeout error after several minutes

Solutions:

Add Time Filter

-- Add TD_INTERVAL for partition pruning
SELECT * FROM large_table
WHERE TD_INTERVAL(time, '-1d', 'JST')

Use Aggregations

-- Instead of raw data
SELECT * FROM huge_table

-- Use aggregations
SELECT date, COUNT(*) as cnt
FROM huge_table
GROUP BY date

Reduce Result Size
```
SELECT * FROM table LIMIT 40
```
Check Query Complexity
- Avoid complex joins on large tables
- Use subqueries to filter data first

Issue: Write Operations Blocked

Symptoms:

"Write operations not enabled"
Cannot execute CREATE, INSERT, UPDATE, DELETE

Solutions:

# Remove existing MCP server
claude mcp remove td

# Re-add with write operations enabled
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_ENABLE_UPDATES=true \
  -- npx @treasuredata/mcp-server

# Restart Claude Code

Warning: Only enable write operations if absolutely necessary and you understand the risks.

Issue: Wrong Region/Site

Symptoms:

Cannot see expected databases
Data appears missing
Slow query performance

Solutions:

# Check your account region in TD console
# Then update MCP configuration

claude mcp remove td
claude mcp add td \
  -e TD_API_KEY=$TD_API_KEY \
  -e TD_SITE=jp01 \
  -- npx @treasuredata/mcp-server

Issue: MCP Tools Not Appearing in Claude Code

Symptoms:

Claude Code doesn't suggest TD tools
Natural language queries don't trigger MCP

Solutions:

Restart Claude Code
```
# Exit and restart
```
Verify MCP Configuration
```
claude mcp list
claude mcp status
```

Check MCP Server Logs

# Claude Code logs location (varies by OS)
# macOS: ~/Library/Logs/Claude/
# Linux: ~/.config/Claude/logs/
# Windows: %APPDATA%\Claude\logs\

Be Explicit in Queries

Instead of: "Show data"
Try: "List tables in my TD database"

Advanced Topics

Multiple MCP Connections

You can set up multiple MCP connections for different environments:

# Production (read-only)
claude mcp add td-prod \
  -e TD_API_KEY=$TD_PROD_API_KEY \
  -e TD_SITE=us01 \
  -e TD_DATABASE=production \
  -- npx @treasuredata/mcp-server

# Staging (with write access)
claude mcp add td-staging \
  -e TD_API_KEY=$TD_STAGING_API_KEY \
  -e TD_SITE=us01 \
  -e TD_DATABASE=staging \
  -e TD_ENABLE_UPDATES=true \
  -- npx @treasuredata/mcp-server

# Development (full access)
claude mcp add td-dev \
  -e TD_API_KEY=$TD_DEV_API_KEY \
  -e TD_SITE=us01 \
  -e TD_DATABASE=development \
  -e TD_ENABLE_UPDATES=true \
  -- npx @treasuredata/mcp-server

In Claude Code, specify which connection:

"Using td-prod, list all databases"
"Using td-staging, create test table"

Custom Configuration Files

Instead of command-line setup, you can manually edit Claude Code's MCP configuration:

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Example Configuration:

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

Using with Other MCP Servers

TD MCP can work alongside other MCP servers:

# Add TD MCP
claude mcp add td -e TD_API_KEY=$TD_API_KEY -- npx @treasuredata/mcp-server

# Add other MCP servers
claude mcp add github -- npx @modelcontextprotocol/server-github
claude mcp add postgres -- npx @modelcontextprotocol/server-postgres

# Use in Claude Code
"Query my TD data and compare with GitHub metrics"

Programmatic Usage

While primarily used through Claude Code, you can also interact with TD MCP programmatically using MCP SDKs.

Security Considerations

API Key Storage
- Never commit API keys to version control
- Use environment variables or secure vaults
- Rotate keys regularly
Read-Only by Default
- Keep TD_ENABLE_UPDATES=false unless necessary
- Create separate read-only API keys for MCP use
Network Security
- MCP communicates over HTTPS
- API keys are never logged by default
- All operations are audited in TD
Least Privilege
- Use API keys with minimal required permissions
- Create database-specific API keys if possible
Multi-User Environments
- Each user should use their own API key
- Avoid sharing MCP configurations

Resources

GitHub Repository: https://github.com/treasure-data/td-mcp-server
npm Package: https://www.npmjs.com/package/@treasuredata/mcp-server
MCP Protocol: https://modelcontextprotocol.io/
TD Documentation: https://docs.treasuredata.com/
Claude Code Documentation: https://docs.claude.com/claude-code

Related Skills

trino: Understanding SQL syntax for MCP queries
hive: Hive-specific functions available through MCP
pytd: Python alternative to MCP for programmatic access
trino-cli: Command-line alternative to MCP

Comparison with Other Tools

Tool	Interface	Best For
TD MCP	Natural language in Claude Code	Conversational data exploration, quick insights
Trino CLI	Command-line SQL	Scripting, automation, terminal workflows
pytd	Python SDK	ETL pipelines, complex transformations, notebooks
TD Console	Web UI	Visualization, sharing, collaboration

Recommendation: Use TD MCP for interactive data exploration and ad-hoc analysis within Claude Code. Use other tools for production pipelines and automation.

Last updated: 2025-01 | TD MCP Server: Public Preview | License: Apache-2.0

Install Skill

SKILL.md

Treasure Data MCP Server

When to Use This Skill

What is TD MCP Server?

Core Principles

1. Installation

2. Setup with Claude Code

3. Configuration Options

4. Using MCP Tools in Claude Code

Available MCP Tools

Data Exploration Tools

1. list_databases

2. list_tables

3. describe_table

4. current_database

5. use_database

Query Execution Tools

6. query (Read-Only)

7. execute (Write Operations)

CDP Tools (Experimental)

8. list_parent_segments

9. get_parent_segment

10. list_segments

11. list_activations

12. get_segment

13. parent_segment_sql

14. segment_sql

Workflow Tools (Experimental)

15. list_projects

16. list_workflows

17. list_sessions

Common Patterns

Pattern 1: Initial Setup and Data Exploration

Pattern 2: Time-Series Data Analysis

Pattern 3: Multi-Database Analysis

Pattern 4: Schema Discovery and Documentation

Pattern 5: Workflow Monitoring

Best Practices

Common Issues and Solutions

Issue: Node.js Version Too Old

Issue: Authentication Failed

Issue: MCP Server Not Found

Issue: Query Timeout

Issue: Write Operations Blocked

Issue: Wrong Region/Site

Issue: MCP Tools Not Appearing in Claude Code

Advanced Topics

Multiple MCP Connections

Custom Configuration Files

Using with Other MCP Servers

Programmatic Usage

Security Considerations

Resources

Related Skills

Comparison with Other Tools