Powerdrill MCP Server

Powerdrill MCP 服务

一个模型上下文协议（MCP）服务，提供与 Powerdrill 数据集交互的工具，使用 Powerdrill 用户 ID 和项目 API 密钥进行身份验证。

如需个人使用 AI 分析数据，或与团队一起使用，请访问 https://chat.powerdrill.ai/。

如果你拥有团队的 Powerdrill 用户 ID 和项目 API 密钥，就可以通过 Powerdrill 开源的 Web 客户端操作数据：

• Node.js 版：https://flow.powerdrill.ai/，也可以试用开源 Web 客户端 https://github.com/powerdrillai/powerdrill-flow。
• Python 版：https://powerdrill-flow.streamlit.app/，也可以试用开源 Web 客户端 https://github.com/powerdrillai/powerdrill-flow-streamlit。

功能

• 使用用户 ID 和项目 API 密钥进行 Powerdrill 身份验证
• 列出 Powerdrill 账户中的可用数据集
• 获取特定数据集的详细信息
• 根据自然语言问题在数据集上创建并运行任务
• 与 Claude Desktop 和其他兼容 MCP 的客户端集成

安装

通过 Smithery 安装

如需通过 Smithery 自动为 Claude Desktop 安装 powerdrill-mcp：

npx -y @smithery/cli install @powerdrillai/powerdrill-mcp --client claude

从 npm 安装

# Install globally
npm install -g @powerdrillai/powerdrill-mcp

# Or run directly with npx
npx @powerdrillai/powerdrill-mcp

从源代码安装

克隆此仓库并安装依赖项：

git clone https://github.com/yourusername/powerdrill-mcp.git
cd powerdrill-mcp
npm install

命令行用法

如果是全局安装：

# Start the MCP server
powerdrill-mcp

如果使用 npx：

# Run the latest version
npx -y @powerdrillai/powerdrill-mcp@latest

运行之前，需要配置包含 Powerdrill 凭据的环境变量：

# Set environment variables
export POWERDRILL_USER_ID="your_user_id"
export POWERDRILL_PROJECT_API_KEY="your_project_api_key"

或者创建一个包含这些值的 .env 文件。

前置条件

要使用此 MCP 服务，你需要拥有 Powerdrill 账户和有效的 API 凭据（用户 ID 和 API 密钥）。获取方式如下：

1. 如果还没有 Powerdrill 团队账户，请注册一个
2. 前往账户设置
3. 找到 API 部分，其中会显示：
   • 用户 ID：账户的唯一标识符
   • API 密钥：用于 API 访问的身份验证令牌

首先，观看此视频教程，了解如何创建 Powerdrill 团队：

然后，观看此视频教程，了解如何设置 API 凭据：

快速设置

设置此服务最简单的方法是使用提供的设置脚本：

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

脚本将：

1. 安装依赖项
2. 构建 TypeScript 代码
3. 如果 .env 文件不存在，则创建该文件
4. 使用基于 npx 的配置（推荐）为 Claude Desktop 和 Cursor 生成配置文件

然后编辑 .env 文件，填入你的实际凭据：

POWERDRILL_USER_ID=your_actual_user_id
POWERDRILL_PROJECT_API_KEY=your_actual_project_api_key

使用前，还要更新生成的配置文件中的凭据。

手动安装

如果你倾向于手动设置：

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Copy the environment example file
cp .env.example .env

# Edit the .env file with your credentials

用法

运行服务

npm start

与 Claude Desktop 集成

1. 打开 Claude Desktop
2. 前往 Settings > Server Settings
3. 使用以下任一配置添加新服务：

选项 1：使用 npx（推荐）

{
  "powerdrill": {
    "command": "npx",
    "args": [
      "-y",
      "@powerdrillai/powerdrill-mcp@latest"
    ],
    "env": {
      "POWERDRILL_USER_ID": "your_actual_user_id",
      "POWERDRILL_PROJECT_API_KEY": "your_actual_project_api_key"
    }
  }
}

选项 2：使用 node 和本地安装

{
  "powerdrill": {
    "command": "node",
    "args": ["/path/to/powerdrill-mcp/dist/index.js"],
    "env": {
      "POWERDRILL_USER_ID": "your_actual_user_id",
      "POWERDRILL_PROJECT_API_KEY": "your_actual_project_api_key"
    }
  }
}

4. 保存配置
5. 重启 Claude Desktop

与 Cursor 集成

1. 打开 Cursor
2. 前往 Settings > MCP Tools
3. 使用以下任一配置添加新的 MCP 工具：

选项 1：使用 npx（推荐）

{
  "powerdrill": {
    "command": "npx",
    "args": [
      "-y",
      "@powerdrillai/powerdrill-mcp@latest"
    ],
    "env": {
      "POWERDRILL_USER_ID": "your_actual_user_id",
      "POWERDRILL_PROJECT_API_KEY": "your_actual_project_api_key"
    }
  }
}

选项 2：使用 node 和本地安装

{
  "powerdrill": {
    "command": "node",
    "args": ["/path/to/powerdrill-mcp/dist/index.js"],
    "env": {
      "POWERDRILL_USER_ID": "your_actual_user_id",
      "POWERDRILL_PROJECT_API_KEY": "your_actual_project_api_key"
    }
  }
}

4. 保存配置
5. 如有需要，重启 Cursor

使用工具

连接后，你可以在与 Claude Desktop、Cursor、Cline、Windsurf 等的对话中使用 Powerdrill 工具：

• 列出数据集：What datasets are available in my Powerdrill account? 或 Show me all my datasets
• 创建数据集：Create a new dataset called "Sales Analytics" 或 Make a new dataset named "Customer Data" with description "Customer information for 2024 analysis"
• 从本地文件创建数据源：Upload the file /Users/your_name/Downloads/sales_data.csv to dataset {dataset_id} 或 Add my local file /path/to/customer_data.xlsx to my {dataset_id} dataset
• 获取数据集概览：Tell me more about this dataset: {dataset_id} 或 Describe the structure of dataset {dataset_id}
• 创建任务：Analyze dataset {dataset_id} with this question: "How has the trend changed over time?" 或 Run a query on {dataset_id} asking "What are the top 10 customers by revenue?"
• 创建会话：Create a new session named "Sales Analysis 2024" for my data analysis 或 Start a session called "Customer Segmentation" for analyzing market data
• 列出数据源：What data sources are available in dataset {dataset_id}? 或 Show me all files in the {dataset_id} dataset
• 列出会话：Show me all my current analysis sessions 或 List my recent data analysis sessions

可用工具

mcp_powerdrill_list_datasets

列出 Powerdrill 账户中的可用数据集。

参数：

• limit（可选）：要返回的数据集最大数量

示例响应：

{
  "datasets": [
    {
      "id": "dataset-dasfadsgadsgas",
      "name": "mydata",
      "description": "my dataset"
    }
  ]
}

mcp_powerdrill_get_dataset_overview

获取特定数据集的详细概览信息。

参数：

• datasetId（必填）：要获取概览信息的数据集 ID

示例响应：

{
  "id": "dset-cm5axptyyxxx298",
  "name": "sales_indicators_2024",
  "description": "A dataset comprising 373 travel bookings with 15 attributes...",
  "summary": "This dataset contains 373 travel bookings with 15 attributes...",
  "exploration_questions": [
    "How does the booking price trend over time based on the BookingTimestamp?",
    "How does the average booking price change with respect to the TravelDate?"
  ],
  "keywords": [
    "Travel Bookings",
    "Booking Trends",
    "Travel Agencies"
  ]
}

mcp_powerdrill_create_job

通过自然语言问题创建数据分析任务。

参数：

• question（必填）：用于分析数据的自然语言问题或提示词
• dataset_id（必填）：要分析的数据集 ID
• datasource_ids（可选）：要分析的数据集中指定数据源 ID 的数组
• session_id（可选）：用于归类相关任务的会话 ID
• stream（可选，默认值：false）：是否流式传输结果
• output_language（可选，默认值："AUTO"）：输出语言
• job_mode（可选，默认值："AUTO"）：任务模式

示例响应：

{
  "job_id": "job-cm3ikdeuj02zk01l1yeuirt77",
  "blocks": [
    {
      "type": "CODE",
      "content": "```python\nimport pandas as pd\n\ndef invoke(input_0: pd.DataFrame) -> pd.DataFrame:\n...",
      "stage": "Analyze"
    },
    {
      "type": "TABLE",
      "url": "https://static.powerdrill.ai/tmp_datasource_cache/code_result/...",
      "name": "trend_data.csv",
      "expires_at": "2024-11-21T09:56:34.290544Z"
    },
    {
      "type": "IMAGE",
      "url": "https://static.powerdrill.ai/tmp_datasource_cache/code_result/...",
      "name": "Trend of Deaths from Natural Disasters Over the Century",
      "expires_at": "2024-11-21T09:56:34.290544Z"
    },
    {
      "type": "MESSAGE",
      "content": "Analysis of Trends in the Number of Deaths from Natural Disasters...",
      "stage": "Respond"
    }
  ]
}

mcp_powerdrill_create_session

创建新会话，将相关任务归类在一起。

参数：

• name（必填）：会话名称，最多 128 个字符
• output_language（可选，默认值："AUTO"）：生成输出时使用的语言。可选项包括："AUTO"、"EN"、"ES"、"AR"、"PT"、"ID"、"JA"、"RU"、"HI"、"FR"、"DE"、"VI"、"TR"、"PL"、"IT"、"KO"、"ZH-CN"、"ZH-TW"
• job_mode（可选，默认值："AUTO"）：会话的任务模式。可选项包括："AUTO"、"DATA_ANALYTICS"
• max_contextual_job_history（可选，默认值：10）：作为下一项任务上下文保留的近期任务最大数量（0-10）
• agent_id（可选，默认值："DATA_ANALYSIS_AGENT"）：Agent 的 ID

示例响应：

{
  "session_id": "session-abcdefghijklmnopqrstuvwxyz"
}

mcp_powerdrill_list_data_sources

列出特定数据集中的数据源。

参数：

• datasetId（必填）：要列出数据源的数据集 ID
• pageNumber（可选，默认值：1）：开始列出的页码
• pageSize（可选，默认值：10）：每页的项目数
• status（可选）：按状态筛选数据源：synching、invalid、synched（多个状态以逗号分隔）

示例响应：

{
  "count": 3,
  "total": 5,
  "page": 1,
  "page_size": 10,
  "data_sources": [
    {
      "id": "dsource-a1b2c3d4e5f6g7h8i9j0",
      "name": "sales_data.csv",
      "type": "CSV",
      "status": "synched",
      "size": 1048576,
      "dataset_id": "dset-cm5axptyyxxx298"
    },
    {
      "id": "dsource-b2c3d4e5f6g7h8i9j0k1",
      "name": "customer_info.xlsx",
      "type": "EXCEL",
      "status": "synched",
      "size": 2097152,
      "dataset_id": "dset-cm5axptyyxxx298"
    },
    {
      "id": "dsource-c3d4e5f6g7h8i9j0k1l2",
      "name": "market_research.pdf",
      "type": "PDF",
      "status": "synched",
      "size": 3145728,
      "dataset_id": "dset-cm5axptyyxxx298"
    }
  ]
}

mcp_powerdrill_list_sessions

列出 Powerdrill 账户中的会话。

参数：

• pageNumber（可选）：开始列出的页码（默认值：1）
• pageSize（可选）：每页的项目数（默认值：10）
• search（可选）：按名称搜索会话

示例响应：

{
  "count": 2,
  "total": 2,
  "sessions": [
    {
      "id": "session-123abc",
      "name": "Product Analysis",
      "job_count": 3,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T11:45:00Z"
    },
    {
      "id": "session-456def",
      "name": "Financial Forecasting",
      "job_count": 5,
      "created_at": "2024-03-10T14:20:00Z",
      "updated_at": "2024-03-12T09:15:00Z"
    }
  ]
}

mcp_powerdrill_create_dataset

在你的 Powerdrill 账户中创建新的数据集。

参数：

• name（必填）：数据集名称，最多可包含 128 个字符
• description（可选）：数据集描述，最多可包含 128 个字符

示例响应：

{
  "id": "dataset-adsdfasafdsfasdgasd",
  "message": "Dataset created successfully"
}

mcp_powerdrill_create_data_source_from_local_file

通过将本地文件上传到指定数据集来创建新的数据源。

参数：

• dataset_id（必填）：要在其中创建数据源的数据集 ID
• file_path（必填）：要上传文件的本地路径
• file_name（可选）：文件的自定义名称，默认为原始文件名
• chunk_size（可选，默认值：5MB）：分块上传时每个分块的大小（字节）

示例响应：

{
  "dataset_id": "dset-cm5axptyyxxx298",
  "data_source": {
    "id": "dsource-a1b2c3d4e5f6g7h8i9j0",
    "name": "sales_data_2024.csv",
    "type": "FILE",
    "status": "synched",
    "size": 2097152
  },
  "file": {
    "name": "sales_data_2024.csv",
    "size": 2097152,
    "object_key": "uploads/user_123/sales_data_2024.csv"
  }
}

故障排除

如果遇到问题：

1. 确保在 .env 中正确设置了环境变量
2. 检查服务器是否通过 npm start 成功启动
3. 确认 Claude Desktop 配置指向了正确的文件路径
4. 检查控制台输出中是否有错误消息

许可证

MIT