Supports loading Treasure Data API credentials from a .env file as an alternative to environment variables.
Treasure Data MCP Server
A Model Context Protocol (MCP) server that provides Treasure Data API integration for Claude Code and Claude Desktop.
DISCLAIMER: This is a personal development project and is not affiliated with, endorsed by, or related to Treasure Data Inc. in any way. This software is provided "as is" without warranty of any kind, and should be used at your own risk. The author is not responsible for any consequences resulting from the use of this software.
Reference Documentation
For comprehensive Treasure Data documentation and tools:
- Official API Documentation: https://api-docs.treasuredata.com/en/overview/gettingstarted/
- CLI Tool (td command): https://github.com/treasure-data/td
- Console Interface: https://console.treasuredata.com/
- Detailed API Guide: docs/treasure-data-api-guide.md
Available MCP Tools
This MCP server provides a comprehensive set of tools for interacting with Treasure Data, organized by functionality. Currently offering 23 tools across 6 categories:
Database Management
- td_list_databases
- Get databases in your Treasure Data account with pagination support
- Parameters:
verbose
: If True, return full details; if False, return only names (default)limit
: Maximum number of databases to retrieve (defaults to 30)offset
: Index to start retrieving from (defaults to 0)all_results
: If True, retrieves all databases ignoring limit and offset
- Examples:
- td_get_database
- Get detailed information about a specific database
- Parameters:
database_name
: The name of the database to retrieve information for
- Example:
- td_list_tables
- Get tables in a specific Treasure Data database with pagination support
- Parameters:
database_name
: The name of the database to retrieve tables fromverbose
: If True, return full details; if False, return only names (default)limit
: Maximum number of tables to retrieve (defaults to 30)offset
: Index to start retrieving from (defaults to 0)all_results
: If True, retrieves all tables ignoring limit and offset
- Examples:
Workflow Project Management
- td_list_projects
- Get workflow projects in your Treasure Data account with pagination support
- Parameters:
verbose
: If True, return full details; if False, return only names and IDs (default)limit
: Maximum number of projects to retrieve (defaults to 30)offset
: Index to start retrieving from (defaults to 0)all_results
: If True, retrieves all projects ignoring limit and offsetinclude_system
: If True, include system-generated projects (with "sys" metadata); defaults to False
- Examples:
- td_get_project
- Get detailed information about a specific workflow project
- Note: This provides basic project metadata only. For detailed content and files, use td_download_project_archive followed by td_list_project_files and td_read_project_file
- Parameters:
project_id
: The ID of the workflow project to retrieve information for
- Example:
- td_download_project_archive
- Download a project's archive (tar.gz) and return information about the download
- Recommended for examining detailed project contents including SQL queries and workflow definitions
- Parameters:
project_id
: The ID of the workflow project to download
- Example:
- td_list_project_files
- List all files contained in a project archive
- Parameters:
archive_path
: The path to the downloaded project archive (.tar.gz file)
- Example:
- td_read_project_file
- Read the contents of a specific file from a project archive
- Parameters:
archive_path
: The path to the downloaded project archive (.tar.gz file)file_path
: The path of the file within the archive to read
- Example:
- td_list_workflows
- Get workflows across all projects in your Treasure Data account
- Parameters:
verbose
: If True, return full details including sessions; if False, return summary (default)count
: Maximum number of workflows to retrieve (defaults to 100, max 12000)include_system
: If True, include system-generated workflows (with "sys" metadata)status_filter
: Filter workflows by their last session status ('success', 'error', 'running', None for all)
- Examples:
Search and Discovery Tools
- td_smart_search
- Intelligent search across all Treasure Data resources with fuzzy matching and relevance scoring
- Parameters:
query
: Search term or phrasesearch_scope
: Where to search - "projects", "workflows", "tables", "all" (default: "all")search_mode
: Search algorithm - "exact", "fuzzy", "semantic" (default: "fuzzy")active_only
: Filter to only active/non-deleted resources (default: True)min_relevance
: Minimum relevance score (0-1) for results (default: 0.7)
- Examples:
- td_find_project
- Find project by name or partial name match
- Parameters:
search_term
: Project name or partial name to search forexact_match
: If True, only return exact matches (default: False)
- Examples:
- td_find_workflow
- Find workflows by name with optional filters
- Parameters:
search_term
: Workflow name or partial name to search forproject_name
: Optional project name to filter byexact_match
: If True, only return exact matches (default: False)status_filter
: Filter by status ('success', 'error', 'running', None)
- Examples:
- td_get_project_by_name
- Get project details by exact name match (convenient alternative to finding ID first)
- Parameters:
project_name
: Exact project name
- Example:
URL Analysis Tools
- td_analyze_url
- Extract and retrieve information from a Treasure Data console URL
- Parameters:
url
: Console URL to analyze
- Supported URL formats:
- Workflow:
https://console.us01.treasuredata.com/app/workflows/12345678/info
- Project:
https://console.us01.treasuredata.com/app/projects/123456
- Job:
https://console.us01.treasuredata.com/app/jobs/123456
- Workflow:
- Example:
- td_get_workflow
- Get workflow details by numeric ID (useful for console URLs)
- Parameters:
workflow_id
: Numeric workflow ID
- Example:
Project Analysis and Diagnostics (New)
- td_explore_project
- Analyze a TD project comprehensively for documentation or debugging
- Parameters:
identifier
: Project name, ID, or search termanalysis_depth
: Level of analysis - "overview", "detailed", or "deep" (default: "detailed")focus_areas
: Specific aspects to analyze - ["code", "data_flow", "performance", "errors"] (default: ["code", "data_flow"])
- Examples:
- td_diagnose_workflow
- Diagnose workflow health and identify issues
- Parameters:
workflow_identifier
: Workflow name, ID, or partial matchtime_window
: Time period to analyze (e.g., "30d", "7d", "24h") (default: "30d")diagnostic_level
: "basic" for quick check, "comprehensive" for deep analysis (default: "basic")
- Examples:
- td_trace_data_lineage
- Trace data dependencies and lineage for tables or projects
- Parameters:
table_or_project
: Table name (format: "database.table") or project name/IDdirection
: "upstream" (sources), "downstream" (consumers), or "both" (default: "both")max_depth
: Maximum levels to trace (default: 3)
- Examples:
Workflow Execution Management Tools
- td_get_session
- Get detailed information about a workflow session
- Parameters:
session_id
: The ID of the session to retrieve
- Examples:
- td_list_sessions
- List recent sessions for workflows
- Parameters:
workflow_id
: Optional workflow ID to filter sessionscount
: Number of recent sessions to retrieve (default 20)
- Examples:
- td_get_attempt
- Get detailed information about a workflow attempt
- Parameters:
attempt_id
: The ID of the attempt to retrieve
- Examples:
- td_get_attempt_tasks
- Get all tasks for a workflow attempt
- Parameters:
attempt_id
: The ID of the attempt
- Examples:
- td_analyze_execution
- Analyze workflow execution from URL or ID
- Parameters:
url_or_id
: Console URL, session ID, or attempt ID
- Examples:
Testing
Integration Testing
To test the MCP tools with real API calls:
The integration test script (test_mcp_integration.py
) safely tests all tools by:
- Using generic search terms (no production data hardcoded)
- Showing only summary results (no sensitive data exposed)
- Testing error handling with invalid inputs
- Requiring explicit API key configuration
Important: Never commit files containing:
- API keys or credentials
- Specific project IDs or names from production
- Detailed query results or data dumps
- Customer or business-sensitive information
Setup Instructions
Authentication
This MCP server requires a Treasure Data API key for authentication, which should be provided via the TD_API_KEY
environment variable. You can also specify the Treasure Data endpoint using the TD_ENDPOINT
environment variable (defaults to api.treasuredata.com
).
Setting up with Claude Code
- Clone the repository
- Install dependencies
- Set up environment variables and run
Setting up with Claude Desktop
Configure this MCP server for use with Claude Desktop by editing your configuration file (claude_desktop_config.json
):
Installation and Requirements
This project requires Python 3.11+ and the following dependencies:
requests>=2.28.0
- HTTP client for API requestspydantic>=2.0.0
- Data validation and serializationmcp[cli]>=1.8.1
- Model Context Protocol framework
Install the dependencies:
Running the Server Directly
You can run the MCP server directly:
Development
Running Tests
Code Formatting and Linting
GitHub Actions formatting fix
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
An MCP server for interacting with Treasure Data API, allowing users to retrieve database information and check server status through natural language queries.
Related MCP Servers
- -securityFlicense-qualityAn MCP server implementation that enables users to interact with the PokeAPI to fetch Pokemon information through natural language queries.Last updated -
- -securityFlicense-qualityAn MCP server for interacting with the HackathonWatch API, allowing users to access hackathon data and related information through natural language commands.Last updated -
- -securityFlicense-qualityAn MCP Server that enables interaction with Ticketmaster's Discovery API for accessing event, venue, and artist information through natural language commands.Last updated -
- -securityFlicense-qualityAn MCP server that enables natural language interaction with Google's Discovery Engine API, allowing users to search, recommend, and manage data through conversational interfaces.Last updated -