Treasure Data MCP Server

How to use

You interact with the MCP server through a client that speaks the MCP protocol. Start the server locally or remotely, provide your Treasure Data API key, and then issue high-level tool requests such as listing databases, querying tables, managing projects, and exploring workflows. You will access a broad set of Treasure Data actions without composing raw API calls. Use the available tools to discover resources, run searches, inspect project contents, and diagnose workflows. All interactions require your API key and the endpoint you target, which the server forwards to Treasure Data.

To get started, configure your MCP client to connect to the server. If you run the server locally via the recommended CLI flow, your client will send requests to the MCP runtime which in turn calls Treasure Data APIs using the provided credentials.

How to install

Prerequisites: Python 3.11 or newer and a working network connection.

# Install Python dependencies
pip install -r requirements.txt

# Start the server using the MCP CLI if you are running locally
export TD_API_KEY="your-api-key"
export TD_ENDPOINT="api.treasuredata.com"  # Optional, defaults to api.treasuredata.com
mcp run td_mcp_server/server.py

Configuration and running the server with Claude Desktop

Configure Claude Desktop to connect to your MCP server by adding a server entry. The configuration should include the runtime command and environment variables needed to authenticate with Treasure Data.

{
  "mcpServers": {
    "td": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/td-mcp-server",
        "run",
        "td_mcp_server/server.py"
      ],
      "env": {
        "TD_API_KEY": "YOUR_API_KEY",
        "TD_ENDPOINT": "api.treasuredata.com"
      }
    }
  }
}

Notes and security

Keep your Treasure Data API key secret. Do not hard-code credentials in shared configurations. Prefer environment variables and secure storage for your keys. When distributing configurations, use placeholders (for example, YOUR_API_KEY) and provide instructions for the user to insert their own credentials.

Troubleshooting and tips

If you encounter authentication or connectivity errors, verify that your TD_API_KEY is correctly exported and that TD_ENDPOINT points to the correct Treasure Data region. Check that the MCP server process is running and listening for client connections. Use the provided tools to verify connectivity and test common operations like listing databases and projects.

Tools and capabilities overview

This MCP server exposes a comprehensive set of Treasure Data actions organized into practical tools. You can discover databases, tables, projects, workflows, and more. The available tools are listed in the project’s tool catalog and enable you to perform typical Treasure Data operations through MCP.

td_list_databases

Get databases in your Treasure Data account with pagination support. Options include verbose, limit, offset, and all_results.

td_get_database

Retrieve detailed information about a specific database by name.

td_list_tables

List tables within a specific database with optional verbosity and pagination.

td_list_projects

List workflow projects with pagination; can include system projects and verbose details.

td_get_project

Get detailed information about a specific workflow project. For full contents, use the archive and list/read project files.

td_download_project_archive

Download a project's archive to inspect contents such as SQL queries and workflow definitions.

td_list_project_files

List all files contained in a downloaded project archive.

td_read_project_file

Read a specific file from a downloaded project archive.

td_list_workflows

List workflows across all projects with optional verbosity, count limit, and system inclusion.

td_smart_search

Perform intelligent search across Treasure Data resources with configurable scope and relevance.

td_find_project

Find a project by name or partial name match.

td_find_workflow

Find workflows by name with optional project filter and status.

td_get_project_by_name

Retrieve project details by exact name match.

td_analyze_url

Analyze a Treasure Data console URL to identify workflow, project, or job references.

td_get_workflow

Get detailed information about a workflow by numeric ID.

td_explore_project

Comprehensive analysis of a Treasure Data project for documentation or debugging.

td_diagnose_workflow

Diagnose workflow health and identify issues over a specified time window.

td_trace_data_lineage

Trace data dependencies and lineage for tables or projects.

td_get_session

Retrieve detailed information about a workflow session.

td_list_sessions

List recent sessions for workflows, optionally filtered by workflow ID.

td_get_attempt

Get detailed information about a workflow attempt.

td_get_attempt_tasks

List all tasks for a workflow attempt.

td_analyze_execution

Analyze a workflow execution from a URL or an ID.