Powerdrill MCP 服务器

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

请访问 https://powerdrill.ai/ 进行个人 AI 数据分析，或与您的团队一起使用。

如果您拥有团队的 Powerdrill 用户 ID 和项目 API 密钥，您可以通过 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 安装

# 全局安装
npm install -g @powerdrillai/powerdrill-mcp

# 或者直接使用 npx 运行
npx @powerdrillai/powerdrill-mcp

从源代码安装

克隆此存储库并安装依赖项：

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

CLI 用法

如果已全局安装：

# 启动 MCP 服务器
powerdrill-mcp

如果使用 npx：

# 运行最新版本
npx -y @powerdrillai/powerdrill-mcp@latest

在运行之前，您需要使用您的 Powerdrill 凭据配置环境变量：

# 设置环境变量
export POWERDRILL_USER_ID="your_user_id"
export POWERDRILL_PROJECT_API_KEY="your_project_api_key"

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

前提条件

要使用此 MCP 服务器，您需要一个具有有效 API 凭据（用户 ID 和 API 密钥）的 Powerdrill 帐户。 获取方法如下：

1. 如果您还没有 Powerdrill 团队帐户，请注册一个
2. 导航到您的帐户设置
3. 查找 API 部分，您将在其中找到：
   • 用户 ID：您帐户的唯一标识符
   • API 密钥：您用于 API 访问的身份验证令牌

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

然后，按照此视频教程设置您的 API 凭据：

快速设置

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

# 使脚本可执行
chmod +x setup.sh

# 运行设置脚本
./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

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

手动安装

如果您喜欢手动设置：

# 安装依赖项
npm install

# 构建 TypeScript 代码
npm run build

# 复制环境示例文件
cp .env.example .env

# 使用您的凭据编辑 .env 文件

用法

运行服务器

npm start

与 Claude Desktop 集成

1. 打开 Claude Desktop
2. 转到设置 > 服务器设置
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. 转到设置 > MCP 工具
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 工具：

• 列出数据集：我的 Powerdrill 帐户中有哪些数据集可用？ 或 显示我所有的数据集
• 创建数据集：创建一个名为“销售分析”的新数据集 或 创建一个名为“客户数据”的新数据集，描述为“用于 2024 年分析的客户信息”
• 从本地文件创建数据源：将文件 /Users/your_name/Downloads/sales_data.csv 上传到数据集 {dataset_id} 或 将我的本地文件 /path/to/customer_data.xlsx 添加到我的 {dataset_id} 数据集
• 获取数据集概述：告诉我更多关于此数据集的信息：{dataset_id} 或 描述数据集 {dataset_id} 的结构
• 创建作业：使用以下问题分析数据集 {dataset_id}：“趋势如何随时间变化？” 或 在 {dataset_id} 上运行查询，询问“收入最高的 10 个客户是谁？”
• 创建会话：为我的数据分析创建一个名为“2024 年销售分析”的新会话 或 启动一个名为“客户细分”的会话来分析市场数据
• 列出数据源：数据集 {dataset_id} 中有哪些数据源可用？ 或 显示 {dataset_id} 数据集中的所有文件
• 列出会话：显示我所有当前的分析会话 或 列出我最近的数据分析会话

可用工具

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": "一个包含 373 个旅行预订和 15 个属性的数据集...",
  "summary": "此数据集包含 373 个旅行预订和 15 个属性...",
  "exploration_questions": [
    "基于 BookingTimestamp，预订价格如何随时间变化？",
    "平均预订价格如何随 TravelDate 变化？"
  ],
  "keywords": [
    "旅行预订",
    "预订趋势",
    "旅行社"
  ]
}

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"）：代理的 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