Powerdrill

Servidor MCP Powerdrill

Um servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com conjuntos de dados do Powerdrill, autenticado com ID de Usuário e Chave de API do Projeto Powerdrill.

Acesse https://chat.powerdrill.ai/ para análise de dados por IA individualmente ou use com sua Equipe.

Se você tiver o ID de Usuário e a Chave de API do Projeto Powerdrill da sua Equipe, poderá manipular os dados através dos clientes web de código aberto do Powerdrill:

• Edição Node.js: https://flow.powerdrill.ai/, ou experimente o cliente web de código aberto https://github.com/powerdrillai/powerdrill-flow.
• Edição Python: https://powerdrill-flow.streamlit.app/, ou experimente o cliente web de código aberto https://github.com/powerdrillai/powerdrill-flow-streamlit.

Funcionalidades

• Autenticação no Powerdrill usando ID de Usuário e Chave de API do Projeto
• Listar conjuntos de dados disponíveis na sua conta Powerdrill
• Obter informações detalhadas sobre conjuntos de dados específicos
• Criar e executar tarefas em conjuntos de dados com perguntas em linguagem natural
• Integração com Claude Desktop e outros clientes compatíveis com MCP

Instalação

Instalando via Smithery

Para instalar o powerdrill-mcp para Claude Desktop automaticamente via Smithery:

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

Do npm

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

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

Do Fonte

Clone este repositório e instale as dependências:

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

Uso via CLI

Se instalado globalmente:

# Start the MCP server
powerdrill-mcp

Se estiver usando npx:

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

Você precisará configurar as variáveis de ambiente com suas credenciais do Powerdrill antes de executar:

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

Ou crie um arquivo .env com esses valores.

Pré-requisitos

Para usar este servidor MCP, você precisará de uma conta Powerdrill com credenciais de API válidas (ID de Usuário e Chave de API). Veja como obtê-las:

1. Cadastre-se para uma conta de Equipe Powerdrill, se ainda não tiver uma
2. Navegue até as configurações da sua conta
3. Procure a seção de API onde você encontrará:
   • ID de Usuário: Um identificador único para sua conta
   • Chave de API: Seu token de autenticação para acesso à API

Primeiro, assista a este tutorial em vídeo sobre como criar sua Equipe Powerdrill:

Em seguida, siga este tutorial em vídeo para configurar suas credenciais de API:

Configuração Rápida

A maneira mais fácil de configurar o servidor é usando o script de configuração fornecido:

# Make the script executable
chmod +x setup.sh

# Run the setup script
./setup.sh

Isso irá:

1. Instalar dependências
2. Compilar o código TypeScript
3. Criar um arquivo .env se ele não existir
4. Gerar arquivos de configuração para Claude Desktop e Cursor com a configuração baseada em npx (recomendado)

Em seguida, edite seu arquivo .env com suas credenciais reais:

POWERDRILL_USER_ID=your_actual_user_id
POWERDRILL_PROJECT_API_KEY=your_actual_project_api_key

Atualize também as credenciais nos arquivos de configuração gerados antes de usá-los.

Instalação Manual

Se preferir configurar manualmente:

# 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

Uso

Executando o servidor

npm start

Integrando com Claude Desktop

1. Abra o Claude Desktop
2. Vá para Configurações > Configurações do Servidor
3. Adicione um novo servidor com uma das seguintes configurações:

Opção 1: Usando npx (Recomendado)

{
  "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"
    }
  }
}

Opção 2: Usando node com instalação local

{
  "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. Salve a configuração
5. Reinicie o Claude Desktop

Integrando com Cursor

1. Abra o Cursor
2. Vá para Configurações > Ferramentas MCP
3. Adicione uma nova ferramenta MCP com uma das seguintes configurações:

Opção 1: Usando npx (Recomendado)

{
  "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"
    }
  }
}

Opção 2: Usando node com instalação local

{
  "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. Salve a configuração
5. Reinicie o Cursor, se necessário

Usando as ferramentas

Uma vez conectado, você pode usar as ferramentas do Powerdrill em suas conversas com Claude Desktop, Cursor, Cline, Windsurf, etc.:

• Listar conjuntos de dados: What datasets are available in my Powerdrill account? ou Show me all my datasets
• Criar conjunto de dados: Create a new dataset called "Sales Analytics" ou Make a new dataset named "Customer Data" with description "Customer information for 2024 analysis"
• Criar fonte de dados a partir de arquivo local: Upload the file /Users/your_name/Downloads/sales_data.csv to dataset {dataset_id} ou Add my local file /path/to/customer_data.xlsx to my {dataset_id} dataset
• Obter visão geral do conjunto de dados: Tell me more about this dataset: {dataset_id} ou Describe the structure of dataset {dataset_id}
• Criar uma tarefa: Analyze dataset {dataset_id} with this question: "How has the trend changed over time?" ou Run a query on {dataset_id} asking "What are the top 10 customers by revenue?"
• Criar uma sessão: Create a new session named "Sales Analysis 2024" for my data analysis ou Start a session called "Customer Segmentation" for analyzing market data
• Listar fontes de dados: What data sources are available in dataset {dataset_id}? ou Show me all files in the {dataset_id} dataset
• Listar sessões: Show me all my current analysis sessions ou List my recent data analysis sessions

Ferramentas Disponíveis

mcp_powerdrill_list_datasets

Lista os conjuntos de dados disponíveis na sua conta Powerdrill.

Parâmetros:

• limit (opcional): Número máximo de conjuntos de dados a retornar

Exemplo de resposta:

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

mcp_powerdrill_get_dataset_overview

Obtém informações detalhadas de visão geral sobre um conjunto de dados específico.

Parâmetros:

• datasetId (obrigatório): O ID do conjunto de dados para obter informações de visão geral

Exemplo de resposta:

{
  "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

Cria uma tarefa para analisar dados com perguntas em linguagem natural.

Parâmetros:

• question (obrigatório): A pergunta ou prompt em linguagem natural para analisar os dados
• dataset_id (obrigatório): O ID do conjunto de dados a ser analisado
• datasource_ids (opcional): Array de IDs de fontes de dados específicas dentro do conjunto de dados a serem analisadas
• session_id (opcional): ID da sessão para agrupar tarefas relacionadas
• stream (opcional, padrão: false): Se deve transmitir os resultados
• output_language (opcional, padrão: "AUTO"): O idioma para a saída
• job_mode (opcional, padrão: "AUTO"): O modo da tarefa

Exemplo de resposta:

{
  "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

Cria uma nova sessão para agrupar tarefas relacionadas.

Parâmetros:

• name (obrigatório): O nome da sessão, que pode ter até 128 caracteres
• output_language (opcional, padrão: "AUTO"): O idioma no qual a saída é gerada. As opções incluem: "AUTO", "EN", "ES", "AR", "PT", "ID", "JA", "RU", "HI", "FR", "DE", "VI", "TR", "PL", "IT", "KO", "ZH-CN", "ZH-TW"
• job_mode (opcional, padrão: "AUTO"): Modo de tarefa para a sessão. As opções incluem: "AUTO", "DATA_ANALYTICS"
• max_contextual_job_history (opcional, padrão: 10): O número máximo de tarefas recentes retidas como contexto para a próxima tarefa (0-10)
• agent_id (opcional, padrão: "DATA_ANALYSIS_AGENT"): O ID do agente

Exemplo de resposta:

{
  "session_id": "session-abcdefghijklmnopqrstuvwxyz"
}

mcp_powerdrill_list_data_sources

Lista fontes de dados em um conjunto de dados específico.

Parâmetros:

• datasetId (obrigatório): O ID do conjunto de dados do qual listar as fontes de dados
• pageNumber (opcional, padrão: 1): O número da página para iniciar a listagem
• pageSize (opcional, padrão: 10): O número de itens em uma única página
• status (opcional): Filtrar fontes de dados por status: synching, invalid, synched (separados por vírgula para múltiplos)

Exemplo de resposta:

{
  "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

Lista sessões da sua conta Powerdrill.

Parâmetros:

• pageNumber (opcional): O número da página para iniciar a listagem (padrão: 1)
• pageSize (opcional): O número de itens em uma única página (padrão: 10)
• search (opcional): Pesquisar sessões por nome

Exemplo de resposta:

{
  "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

Cria um novo conjunto de dados na sua conta Powerdrill.

Parâmetros:

• name (obrigatório): O nome do conjunto de dados, que pode ter até 128 caracteres
• description (opcional): A descrição do conjunto de dados, que pode ter até 128 caracteres

Exemplo de resposta:

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

mcp_powerdrill_create_data_source_from_local_file

Cria uma nova fonte de dados enviando um arquivo local para um conjunto de dados especificado.

Parâmetros:

• dataset_id (obrigatório): O ID do conjunto de dados no qual criar a fonte de dados
• file_path (obrigatório): O caminho local para o arquivo a ser enviado
• file_name (opcional): Nome personalizado para o arquivo, padrão é o nome do arquivo original
• chunk_size (opcional, padrão: 5MB): Tamanho de cada parte em bytes para upload multipart

Exemplo de resposta:

{
  "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"
  }
}

Solução de Problemas

Se você encontrar problemas:

1. Certifique-se de que suas variáveis de ambiente estão definidas corretamente em .env
2. Verifique se o servidor inicia com sucesso com npm start
3. Verifique se a configuração do Claude Desktop aponta para os caminhos de arquivo corretos
4. Verifique a saída do console para quaisquer mensagens de erro

Licença

MIT