Productive.io

Interaja com a API do Productive.io para gerenciamento de projetos e tarefas de produtividade.

Documentação

Servidor MCP Productive.io

Um servidor MCP (Model Context Protocol) que permite que o Claude Desktop, o Claude Code e outros clientes compatíveis com MCP interajam com a API do Productive.io.

Recursos

Briefing de Tarefas: get_task_overview retorna tudo sobre uma tarefa em uma única chamada, para que a leitura de um problema não custe uma dúzia de idas e voltas
Empresas e Projetos: Liste empresas e projetos com filtro de status
Pastas: CRUD completo com arquivamento/restauração para organizar o conteúdo do projeto
Listas de Tarefas: Gerenciamento completo do ciclo de vida — criar, atualizar, arquivar/restaurar, copiar, mover, reposicionar
Gerenciamento de Tarefas: Listar, criar, atualizar, excluir tarefas com vários filtros
Subtarefas: Criar e listar subtarefas sob tarefas pai
Operações de Tarefas: Comentários, atualizações de status, atribuição de sprint, reposicionamento
Comentários: CRUD completo com fixar/desafixar e reações
Todos: Itens de checklist em tarefas — criar, atualizar, fechar/reabrir, excluir
Páginas/Docs: Gerenciamento completo de documentos com hierarquias de páginas aninhadas, mover e copiar
Gerenciamento de Pessoas: Liste pessoas na sua organização com opções de filtro
Gerenciamento de Fluxo de Trabalho: Liste e trabalhe com status de fluxo de trabalho para atualizações adequadas de status de tarefas
Controle de Tempo: Liste e crie registros de tempo com integração de serviço/negócio
Contexto do Usuário: Suporta referências "me" quando PRODUCTIVE_USER_ID está configurado
Rastreamento de Atividades: Veja atividades e atualizações recentes em toda a sua organização

Instalação

Via npm (Recomendado)

Instale globalmente:

npm install -g productive-mcp

Ou execute diretamente com npx (sem necessidade de instalação):

npx productive-mcp

A partir do código-fonte

Clone este repositório
Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```

Configuração

Obtendo Suas Credenciais

Para obter suas credenciais do Productive.io:

Faça login no Productive.io
Vá em Configurações → Integrações de API
Gere um novo token (escolha somente leitura por segurança, ou acesso total para criação de tarefas)
Copie o token e o ID da organização

Para encontrar seu ID de usuário:

Você pode usar a API para listar pessoas e encontrar seu ID
Ou verifique a URL ao visualizar seu perfil no Productive.io

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

Variável	Obrigatória	Descrição
`PRODUCTIVE_API_TOKEN`	Sim	Seu token da API do Productive.io
`PRODUCTIVE_ORG_ID`	Sim	Seu ID de organização
`PRODUCTIVE_USER_ID`	Não	Seu ID de usuário (obrigatório para a ferramenta `my_tasks`)

Uso com o Claude Desktop

Adicione o servidor ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Usando npx (Recomendado)

{
  "mcpServers": {
    "productive": {
      "command": "npx",
      "args": ["-y", "productive-mcp"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_organization_id_here",
        "PRODUCTIVE_USER_ID": "your_user_id_here"
      }
    }
  }
}

Usando Instalação Global

{
  "mcpServers": {
    "productive": {
      "command": "productive-mcp",
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_organization_id_here",
        "PRODUCTIVE_USER_ID": "your_user_id_here"
      }
    }
  }
}

Usando Build Local

{
  "mcpServers": {
    "productive": {
      "command": "node",
      "args": ["/path/to/productive-mcp/build/index.js"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_organization_id_here",
        "PRODUCTIVE_USER_ID": "your_user_id_here"
      }
    }
  }
}

Observação: PRODUCTIVE_USER_ID é opcional, mas obrigatório para que a ferramenta my_tasks funcione.

Após adicionar a configuração, reinicie o Claude Desktop.

Uso com o Claude Code

Adicione o servidor à sua configuração do Claude Code usando a CLI:

claude mcp add productive -- npx -y productive-mcp

Em seguida, defina suas variáveis de ambiente. Você pode:

Opção 1: Adicionar ao seu perfil de shell (~/.zshrc ou ~/.bashrc):

export PRODUCTIVE_API_TOKEN="your_api_token_here"
export PRODUCTIVE_ORG_ID="your_organization_id_here"
export PRODUCTIVE_USER_ID="your_user_id_here"

Opção 2: Criar um script wrapper e adicioná-lo como servidor MCP:

Crie um arquivo de script (ex.: ~/scripts/productive-mcp.sh):

#!/bin/bash
export PRODUCTIVE_API_TOKEN="your_api_token_here"
export PRODUCTIVE_ORG_ID="your_organization_id_here"
export PRODUCTIVE_USER_ID="your_user_id_here"
npx -y productive-mcp

Torne-o executável:
```
chmod +x ~/scripts/productive-mcp.sh
```

Adicione ao Claude Code:

claude mcp add productive ~/scripts/productive-mcp.sh

Opção 3: Edite o arquivo de configurações do Claude Code diretamente em ~/.claude/settings.json:

{
  "mcpServers": {
    "productive": {
      "command": "npx",
      "args": ["-y", "productive-mcp"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_organization_id_here",
        "PRODUCTIVE_USER_ID": "your_user_id_here"
      }
    }
  }
}

Reinicie o Claude Code após a configuração.

Ferramentas Disponíveis

Lendo uma tarefa para a qual você recebeu o ID

Use get_task_overview primeiro. Ela responde "sobre o que é este problema" em uma única chamada:

get_task_overview(task_id: "19300600")

Ela retorna metadados (status, responsável, projeto, lista de tarefas, datas, estimativa vs. tempo trabalhado), a descrição original completa e, em seguida, os 10 comentários mais recentes com seus corpos completos em ordem cronológica. O HTML é convertido em texto simples e os blobs @mention são recolhidos em nomes, para que o tópico seja lido como prosa.

Os anexos são exibidos de duas maneiras, porque a maioria deles são capturas de tela que carregam o contexto que você precisa:

Em linha, no ponto exato do comentário em que a captura de tela foi postada, como [attachment 9131629: Screenshot_2026-07-31_110620.png].
Indexados, em um bloco ATTACHMENTS no final listando todos os anexos da tarefa e dos comentários exibidos, sinalizados como [IMAGE], com o comentário de origem e o autor.

Em seguida, busque apenas os que importam com get_attachment(attachment_id: "9131629"), que retorna imagens em linha.

O caminho mais antigo (get_task, depois list_comments, e então um get_comment por comentário truncado) ainda funciona, mas custa uma ida e volta por comentário e trunca os corpos em 200 caracteres.

Ferramentas de Usuário e Contexto

Ferramenta	Descrição
`whoami`	Obter contexto do usuário atual e ID de usuário configurado

Ferramentas de Empresa e Projeto

Ferramenta	Descrição
`list_companies`	Listar empresas/clientes. Filtrar por `status` (ativo/arquivado), `limit`
`list_projects`	Listar projetos. Filtrar por `status`, `company_id`, `limit`

Ferramentas de Pasta

Ferramenta	Descrição
`list_folders`	Listar pastas em um projeto. Filtrar por `project_id`, `status` (1=ativo, 2=arquivado), `limit`
`get_folder`	Obter detalhes da pasta por `folder_id`
`create_folder`	Criar uma pasta. Requer `project_id`, `name`
`update_folder`	Renomear uma pasta. Requer `folder_id`, opcional `name`
`archive_folder`	Arquivar uma pasta por `folder_id`
`restore_folder`	Restaurar uma pasta arquivada por `folder_id`

Ferramentas de Quadro e Lista de Tarefas

Ferramenta	Descrição
`list_boards`	Listar quadros. Filtrar por `project_id`, `limit`
`create_board`	Criar um quadro. Requer `project_id`, `name`
`list_task_lists`	Listar listas de tarefas. Filtrar por `board_id`, `limit`
`create_task_list`	Criar uma lista de tarefas. Requer `board_id`, `project_id`, `name`
`get_task_list`	Obter detalhes da lista de tarefas por `task_list_id`
`update_task_list`	Renomear uma lista de tarefas. Requer `task_list_id`, opcional `name`
`archive_task_list`	Arquivar uma lista de tarefas por `task_list_id`
`restore_task_list`	Restaurar uma lista de tarefas arquivada por `task_list_id`
`copy_task_list`	Copiar uma lista de tarefas. Requer `name`, `template_id`, `project_id`, `board_id`. Opcional `copy_open_tasks`, `copy_assignees`
`move_task_list`	Mover uma lista de tarefas para outro quadro. Requer `task_list_id`, `board_id`
`reposition_task_list`	Reordenar uma lista de tarefas. Requer `task_list_id`, `move_before_id`

Ferramentas de Gerenciamento de Tarefas

Ferramenta	Descrição
`get_task_overview`	Comece aqui para qualquer ID de tarefa. Uma chamada retorna metadados, a descrição completa, os comentários mais recentes na íntegra (padrão 10, `comment_limit` até 50) do mais antigo para o mais novo, e um índice de todos os anexos da tarefa e desses comentários. Requer `task_id`
`list_tasks`	Listar tarefas. Filtrar por `project_id`, `assignee_id`, `status` (aberta/fechada), `limit`
`get_project_tasks`	Obter todas as tarefas de um projeto. Requer `project_id`, opcional `status`
`get_task`	Obter detalhes da tarefa por `task_id`. Apenas metadados, sem comentários. Prefira `get_task_overview`
`create_task`	Criar uma tarefa. Requer `title`. Opcional `project_id`, `board_id`, `task_list_id`, `assignee_id` ("me" suportado), `due_date`, `status`
`update_task_assignment`	Atribuir/desatribuir uma tarefa. Requer `task_id`, `assignee_id` ("me" ou "null" suportados)
`update_task_details`	Atualizar título/descrição. Requer `task_id`, opcional `title`, `description`, `description_html`
`update_task_status`	Definir status do fluxo de trabalho por nome ou ID. Requer `task_id` e `status_name` (ex.: "Em Andamento", "Em Espera") ou `workflow_status_id`. Resolve automaticamente o fluxo de trabalho do projeto da tarefa, suporta status personalizados
`delete_task`	Excluir uma tarefa por `task_id`
`my_tasks`	Obter tarefas atribuídas a você. Opcional `status`, `limit`
`reposition_task`	Reordenar uma tarefa dentro de uma lista
`update_task_sprint`	Mover tarefa para um sprint/lista de tarefas
`move_task_to_list`	Mover uma tarefa para uma lista de tarefas diferente
`add_to_backlog`	Mover uma tarefa para o backlog

Ferramentas de Dependência de Tarefas

Ferramenta	Descrição
`list_task_dependencies`	Listar dependências de uma tarefa. Filtrar por `task_id` (o que ela bloqueia) ou `dependent_task_id` (o que a bloqueia)
`get_task_dependency`	Obter detalhes da dependência por `dependency_id`
`create_task_dependency`	Criar uma dependência. Requer `task_id` (bloqueador), `dependent_task_id` (bloqueado). Opcional `type_id`: 1 = bloqueia (padrão), 2 = é bloqueado por, 3 = relacionado a
`delete_task_dependency`	Remover uma dependência por `dependency_id`

Ferramentas de Subtarefa

Ferramenta	Descrição
`list_subtasks`	Listar subtarefas de uma tarefa pai. Requer `parent_task_id`, opcional `limit`
`create_subtask`	Criar uma subtarefa. Requer `parent_task_id`, `title`. Opcional `project_id`, `task_list_id`, `assignee_id`, `due_date`, `description`

Ferramentas de Comentário

Ferramenta	Descrição
`add_task_comment`	Adicionar um comentário a uma tarefa. Requer `task_id`, `comment` (suporta HTML e @menções). Opcional `hidden` (booleano) publica um comentário interno não visível para clientes no portal do cliente
`list_comments`	Listar comentários. Filtrar por `task_id`, `project_id`, `limit`. Os corpos são truncados em 200 caracteres; para ler o tópico de uma tarefa, use `get_task_overview`
`get_comment`	Obter detalhes completos do comentário por `comment_id`
`update_comment`	Editar um comentário. Requer `comment_id`, `body`
`delete_comment`	Excluir um comentário por `comment_id`
`pin_comment`	Fixar um comentário por `comment_id`
`unpin_comment`	Desafixar um comentário por `comment_id`
`add_comment_reaction`	Adicionar uma reação. Requer `comment_id`, `reaction` (ex.: "like")

Ferramentas de Todo

Ferramenta	Descrição
`list_todos`	Listar todos em uma tarefa. Filtrar por `task_id`, `status` (aberto/fechado), `limit`
`get_todo`	Obter detalhes do todo por `todo_id`
`create_todo`	Criar um todo. Requer `description`. Opcional `task_id`, `deal_id`, `assignee_id`, `due_date`
`update_todo`	Atualizar um todo. Requer `todo_id`. Opcional `description`, `closed` (booleano), `due_date`
`delete_todo`	Excluir um todo por `todo_id`

Ferramentas de Página/Documento

Ferramenta	Descrição
`list_pages`	Listar páginas. Filtrar por `project_id`, `sort` (title/created_at/edited_at/updated_at), `limit`
`get_page`	Obter conteúdo completo da página por `page_id`
`create_page`	Criar uma página. Requer `project_id`, `title`. Opcional `body` (HTML), `parent_page_id`, `root_page_id`
`update_page`	Atualizar uma página. Requer `page_id`. Opcional `title`, `body`
`delete_page`	Excluir uma página por `page_id`
`move_page`	Mover página para baixo de outra. Requer `page_id`, `target_doc_id`
`copy_page`	Copiar uma página. Requer `template_id`. Opcional `project_id`

Ferramentas de Fluxo de Trabalho

Ferramenta	Descrição
`list_workflow_statuses`	Listar status de fluxo de trabalho. Filtrar por `workflow_id`, `category_id` (1=Não iniciado, 2=Iniciado, 3=Fechado), `limit`

Ferramentas de Controle de Tempo

Ferramenta	Descrição
`list_time_entries`	Listar entradas de tempo. Filtrar por `date`, `after`, `before`, `person_id`, `project_id`, `task_id`, `service_id`
`create_time_entry`	Criar uma entrada de tempo. Requer `date`, `time` (minutos), `person_id`, `service_id`. Opcional `task_id`, `note`
`list_services`	Listar serviços. Filtrar por `company_id`, `limit`
`get_project_services`	Obter serviços para um projeto
`list_project_deals`	Listar negócios/orçamentos para um projeto
`list_deal_services`	Listar serviços para um negócio/orçamento

Ferramentas de Atividade e Atualizações

Ferramenta	Descrição
`list_activities`	Listar atividades. Filtrar por `task_id`, `project_id`, `person_id`, `item_type`, `event`, `after`, `before`
`get_recent_updates`	Obter atualizações recentes. Opcional `limit`, `hours`

Fluxos de Trabalho Comuns

Atualizando o Status da Tarefa

Você pode atualizar o status de uma tarefa pelo nome — sem necessidade de procurar IDs:

update_task_status {
  "task_id": "12399194",
  "status_name": "On Hold"
}

A ferramenta resolve automaticamente o fluxo de trabalho do projeto da tarefa e corresponde ao nome do status (sem diferenciar maiúsculas/minúsculas, suporta correspondência parcial). Isso também funciona com status de fluxo de trabalho personalizados.

Se o nome não corresponder ou for ambíguo, ela retorna os status disponíveis para aquele projeto:

No workflow status matching "banana" found.

Available statuses:
  • "Pending" (ID: 102305) — Not Started
  • "Open" (ID: 102291) — Started
  • "On Hold" (ID: 102306) — Started
  • "Waiting" (ID: 102307) — Started
  • "Closed" (ID: 102292) — Closed

Você também pode passar workflow_status_id diretamente se já souber o ID.

Trabalhando com o Contexto "me"

Quando PRODUCTIVE_USER_ID está configurado, você pode usar "me" em várias ferramentas:

create_task com "assignee_id": "me"
update_task_assignment com "assignee_id": "me"
my_tasks para obter suas tarefas atribuídas
whoami para verificar seu contexto de usuário configurado

Criando Fluxos de Trabalho de Tarefas Completos

Criar uma pasta: create_folder
Criar listas de tarefas: create_task_list
Criar tarefas: create_task
Dividir o trabalho: create_subtask para subitens, create_todo para listas de verificação
Adicionar comentários: add_task_comment
Atualizar status: update_task_status com status_name (por exemplo, "Aberto", "Em espera", "Fechado")
Acompanhar o progresso: Use list_activities ou get_recent_updates

Construindo Documentação

Criar uma página raiz: create_page com project_id e title
Adicionar páginas filhas: create_page com parent_page_id e root_page_id definidos para a raiz
Aninhar mais profundamente: Defina parent_page_id para o pai e root_page_id para a página raiz
Reorganizar: Use move_page para reatribuir páginas, copy_page para duplicar

Desenvolvimento

Executar em modo de desenvolvimento: npm run dev
Compilar: npm run build
Iniciar servidor compilado: npm start

Licença

ISC