Productive.io

Interactúa con la API de Productive.io para la gestión de proyectos y tareas de productividad.

Documentación

Servidor MCP de Productive.io

Un servidor MCP (Protocolo de Contexto de Modelo) que permite a Claude Desktop, Claude Code y otros clientes compatibles con MCP interactuar con la API de Productive.io.

Características

Informe de tareas: get_task_overview devuelve todo sobre una tarea en una sola llamada, por lo que leer un problema no cuesta una docena de idas y vueltas
Empresas y proyectos: Lista empresas y proyectos con filtrado por estado
Carpetas: CRUD completo con archivar/restaurar para organizar el contenido del proyecto
Listas de tareas: Gestión completa del ciclo de vida: crear, actualizar, archivar/restaurar, copiar, mover, reposicionar
Gestión de tareas: Listar, crear, actualizar, eliminar tareas con varios filtros
Subtareas: Crear y listar subtareas bajo tareas principales
Operaciones de tareas: Comentarios, actualizaciones de estado, asignación a sprints, reposicionamiento
Comentarios: CRUD completo con fijar/desfijar y reacciones
Todos: Elementos de lista de verificación en tareas: crear, actualizar, cerrar/reabrir, eliminar
Páginas/Documentos: Gestión completa de documentos con jerarquías de páginas anidadas, mover y copiar
Gestión de personas: Lista personas en tu organización con opciones de filtrado
Gestión de flujos de trabajo: Lista y trabaja con estados de flujo de trabajo para actualizaciones adecuadas de estado de tareas
Seguimiento de tiempo: Lista y crea entradas de tiempo con integración de servicio/acuerdo
Contexto de usuario: Admite referencias "me" cuando PRODUCTIVE_USER_ID está configurado
Seguimiento de actividad: Ve actividades y actualizaciones recientes en toda tu organización

Instalación

Vía npm (Recomendado)

Instalar globalmente:

npm install -g productive-mcp

O ejecutar directamente con npx (sin necesidad de instalación):

npx productive-mcp

Desde el código fuente

Clona este repositorio
Instala las dependencias:
```
npm install
```
Compila el proyecto:
```
npm run build
```

Configuración

Obtención de tus credenciales

Para obtener tus credenciales de Productive.io:

Inicia sesión en Productive.io
Ve a Configuración → Integraciones de API
Genera un nuevo token (elige solo lectura por seguridad, o acceso completo para creación de tareas)
Copia el token y el ID de organización

Para encontrar tu ID de usuario:

Puedes usar la API para listar personas y encontrar tu ID
O revisa la URL al ver tu perfil en Productive.io

Variables de entorno

El servidor requiere las siguientes variables de entorno:

Variable	Requerida	Descripción
`PRODUCTIVE_API_TOKEN`	Sí	Tu token de API de Productive.io
`PRODUCTIVE_ORG_ID`	Sí	Tu ID de organización
`PRODUCTIVE_USER_ID`	No	Tu ID de usuario (requerido para la herramienta `my_tasks`)

Uso con Claude Desktop

Agrega el servidor a tu archivo de configuración de 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 instalación 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 compilación 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"
      }
    }
  }
}

Nota: PRODUCTIVE_USER_ID es opcional pero requerido para que la herramienta my_tasks funcione.

Después de agregar la configuración, reinicia Claude Desktop.

Uso con Claude Code

Agrega el servidor a tu configuración de Claude Code usando la CLI:

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

Luego configura tus variables de entorno. Puedes:

Opción 1: Agregar a tu perfil de shell (~/.zshrc o ~/.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"

Opción 2: Crear un script contenedor y agregarlo como servidor MCP:

Crea un archivo de script (por ejemplo, ~/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

Hazlo ejecutable:
```
chmod +x ~/scripts/productive-mcp.sh
```

Agrégalo a Claude Code:

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

Opción 3: Edita el archivo de configuración de Claude Code directamente en ~/.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"
      }
    }
  }
}

Reinicia Claude Code después de la configuración.

Herramientas disponibles

Leer una tarea de la que tienes el ID

Usa get_task_overview primero. Responde "de qué trata este problema" en una sola llamada:

get_task_overview(task_id: "1000001")

Devuelve metadatos (estado, asignado, proyecto, lista de tareas, fechas, estimación vs tiempo trabajado), la descripción original completa, y luego los 10 comentarios más recientes con sus cuerpos completos en orden cronológico. El HTML se convierte a texto plano y los blobs de @mention se colapsan a nombres, por lo que el hilo se lee como prosa.

Los adjuntos se muestran de dos maneras, porque la mayoría son capturas de pantalla que contienen el contexto que necesitas:

En línea, en el punto exacto del comentario donde se publicó la captura, como [attachment 5000001: Screenshot.png].
Indexados, en un bloque de ATTACHMENTS al final que lista cada adjunto en la tarea y en los comentarios mostrados, marcados como [IMAGE], con el comentario fuente y el autor.

Luego obtén solo los que importan con get_attachment(attachment_id: "5000001"), que devuelve imágenes en línea.

La ruta anterior (get_task, luego list_comments, y luego un get_comment por comentario truncado) sigue funcionando, pero cuesta una ida y vuelta por comentario y trunca los cuerpos a 200 caracteres.

Herramientas de usuario y contexto

Herramienta	Descripción
`whoami`	Obtener el contexto del usuario actual y el ID de usuario configurado

Herramientas de empresas y proyectos

Herramienta	Descripción
`list_companies`	Listar empresas/clientes. Filtrar por `status` (activo/archivado), `limit`
`list_projects`	Listar proyectos. Filtrar por `status`, `company_id`, `limit`

Herramientas de carpetas

Herramienta	Descripción
`list_folders`	Listar carpetas en un proyecto. Filtrar por `project_id`, `status` (1=activo, 2=archivado), `limit`
`get_folder`	Obtener detalles de carpeta por `folder_id`
`create_folder`	Crear una carpeta. Requiere `project_id`, `name`
`update_folder`	Renombrar una carpeta. Requiere `folder_id`, opcional `name`
`archive_folder`	Archivar una carpeta por `folder_id`
`restore_folder`	Restaurar una carpeta archivada por `folder_id`

Herramientas de tableros y listas de tareas

Herramienta	Descripción
`list_boards`	Listar tableros. Filtrar por `project_id`, `limit`
`create_board`	Crear un tablero. Requiere `project_id`, `name`
`list_task_lists`	Listar listas de tareas. Filtrar por `board_id`, `limit`
`create_task_list`	Crear una lista de tareas. Requiere `board_id`, `project_id`, `name`
`get_task_list`	Obtener detalles de lista de tareas por `task_list_id`
`update_task_list`	Renombrar una lista de tareas. Requiere `task_list_id`, opcional `name`
`archive_task_list`	Archivar una lista de tareas por `task_list_id`
`restore_task_list`	Restaurar una lista de tareas archivada por `task_list_id`
`copy_task_list`	Copiar una lista de tareas. Requiere `name`, `template_id`, `project_id`, `board_id`. Opcional `copy_open_tasks`, `copy_assignees`
`move_task_list`	Mover una lista de tareas a otro tablero. Requiere `task_list_id`, `board_id`
`reposition_task_list`	Reordenar una lista de tareas. Requiere `task_list_id`, `move_before_id`

Herramientas de gestión de tareas

Herramienta	Descripción
`get_task_overview`	Empieza aquí para cualquier ID de tarea. Una llamada devuelve metadatos, la descripción completa, los comentarios más recientes completos (por defecto 10, `comment_limit` hasta 50) del más antiguo al más nuevo, y un índice de cada adjunto en la tarea y esos comentarios. Requiere `task_id`
`list_tasks`	Listar tareas. Filtrar por `project_id`, `assignee_id`, `status` (abierta/cerrada), `limit`
`get_project_tasks`	Obtener todas las tareas de un proyecto. Requiere `project_id`, opcional `status`
`get_task`	Obtener detalles de tarea por `task_id`. Solo metadatos, sin comentarios. Prefiere `get_task_overview`
`create_task`	Crear una tarea. Requiere `title`. Opcional `project_id`, `board_id`, `task_list_id`, `assignee_id` (se admite "me"), `due_date`, `status`
`update_task_assignment`	Asignar/desasignar una tarea. Requiere `task_id`, `assignee_id` (se admite "me" o "null")
`update_task_details`	Actualizar título/descripción. Requiere `task_id`, opcional `title`, `description`, `description_html`
`update_task_status`	Establecer estado de flujo de trabajo por nombre o ID. Requiere `task_id` y ya sea `status_name` (por ejemplo, "En progreso", "En espera") o `workflow_status_id`. Resuelve automáticamente el flujo de trabajo del proyecto de la tarea, admite estados personalizados
`delete_task`	Eliminar una tarea por `task_id`
`my_tasks`	Obtener tareas asignadas a ti. Opcional `status`, `limit`
`reposition_task`	Reordenar una tarea dentro de una lista
`update_task_sprint`	Mover tarea a un sprint/lista de tareas
`move_task_to_list`	Mover una tarea a una lista de tareas diferente
`add_to_backlog`	Mover una tarea al backlog

Herramientas de dependencias de tareas

Herramienta	Descripción
`list_task_dependencies`	Listar dependencias de una tarea. Filtrar por `task_id` (lo que bloquea) o `dependent_task_id` (lo que la bloquea)
`get_task_dependency`	Obtener detalles de dependencia por `dependency_id`
`create_task_dependency`	Crear una dependencia. Requiere `task_id` (bloqueador), `dependent_task_id` (bloqueado). Opcional `type_id`: 1 = bloquea (por defecto), 2 = es bloqueado por, 3 = relacionado con
`delete_task_dependency`	Eliminar una dependencia por `dependency_id`

Herramientas de subtareas

Herramienta	Descripción
`list_subtasks`	Listar subtareas de una tarea principal. Requiere `parent_task_id`, opcional `limit`
`create_subtask`	Crear una subtarea. Requiere `parent_task_id`, `title`. Opcional `project_id`, `task_list_id`, `assignee_id`, `due_date`, `description`

Herramientas de comentarios

Herramienta	Descripción
`add_task_comment`	Agregar un comentario a una tarea. Requiere `task_id`, `comment` (admite HTML y @menciones). Opcional `hidden` (booleano) publica un comentario interno no visible para los clientes en el portal de clientes
`list_comments`	Listar comentarios. Filtrar por `task_id`, `project_id`, `limit`. Los cuerpos se truncan a 200 caracteres; para leer el hilo de una tarea usa `get_task_overview` en su lugar
`get_comment`	Obtener detalles completos de comentario por `comment_id`
`update_comment`	Editar un comentario. Requiere `comment_id`, `body`
`delete_comment`	Eliminar un comentario por `comment_id`
`pin_comment`	Fijar un comentario por `comment_id`
`unpin_comment`	Desfijar un comentario por `comment_id`
`add_comment_reaction`	Agregar una reacción. Requiere `comment_id`, `reaction` (por ejemplo, "like")

Herramientas de todos

Herramienta	Descripción
`list_todos`	Listar todos en una tarea. Filtrar por `task_id`, `status` (abierto/cerrado), `limit`
`get_todo`	Obtener detalles de todo por `todo_id`
`create_todo`	Crear un todo. Requiere `description`. Opcional `task_id`, `deal_id`, `assignee_id`, `due_date`
`update_todo`	Actualizar un todo. Requiere `todo_id`. Opcional `description`, `closed` (booleano), `due_date`
`delete_todo`	Eliminar un todo por `todo_id`

Herramientas de páginas/documentos

Herramienta	Descripción
`list_pages`	Listar páginas. Filtrar por `project_id`, `sort` (title/created_at/edited_at/updated_at), `limit`
`get_page`	Obtener contenido completo de página por `page_id`
`create_page`	Crear una página. Requiere `project_id`, `title`. Opcional `body` (HTML), `parent_page_id`, `root_page_id`
`update_page`	Actualizar una página. Requiere `page_id`. Opcional `title`, `body`
`delete_page`	Eliminar una página por `page_id`
`move_page`	Mover página bajo otra. Requiere `page_id`, `target_doc_id`
`copy_page`	Copiar una página. Requiere `template_id`. Opcional `project_id`

Herramientas de flujo de trabajo

Herramienta	Descripción
`list_workflow_statuses`	Listar estados de flujo de trabajo. Filtrar por `workflow_id`, `category_id` (1=No iniciado, 2=Iniciado, 3=Cerrado), `limit`

Herramientas de seguimiento de tiempo

Herramienta	Descripción
`list_time_entries`	Listar entradas de tiempo. Filtrar por `date`, `after`, `before`, `person_id`, `project_id`, `task_id`, `service_id`
`create_time_entry`	Crear una entrada de tiempo. Requiere `date`, `time` (minutos), `person_id`, `service_id`. Opcional `task_id`, `note`
`update_time_entry`	Modificar una entrada de tiempo por `time_entry_id`. Opcional `time`, `note`, `date`, `service_id`, `billable_time`. Solo se cambian los campos proporcionados
`delete_time_entry`	Eliminar permanentemente una entrada de tiempo por `time_entry_id`. Requiere `confirm: true` en una segunda llamada
`list_services`	Listar servicios. Filtrar por `company_id`, `limit`
`get_project_services`	Obtener servicios para un proyecto
`list_project_deals`	Listar acuerdos/presupuestos para un proyecto
`list_deal_services`	Listar servicios para un acuerdo/presupuesto

Herramientas de actividad y actualizaciones

Herramienta	Descripción
`list_activities`	Listar actividades. Filtrar por `task_id`, `project_id`, `person_id`, `item_type`, `event`, `after`, `before`
`get_recent_updates`	Obtener actualizaciones recientes. Opcional `limit`, `hours`

Flujos de trabajo comunes

Actualizar el estado de una tarea

Puedes actualizar el estado de una tarea por nombre, sin necesidad de buscar IDs:

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

La herramienta resuelve automáticamente el flujo de trabajo del proyecto de la tarea y coincide con el nombre del estado (sin distinguir mayúsculas/minúsculas, admite coincidencia parcial). Esto también funciona con estados de flujo de trabajo personalizados.

Si el nombre no coincide o es ambiguo, devuelve los estados disponibles para ese proyecto:

No workflow status matching "banana" found.

Available statuses:
  • "Pending" (ID: 100001) — Not Started
  • "Open" (ID: 100002) — Started
  • "On Hold" (ID: 100003) — Started
  • "Waiting" (ID: 100004) — Started
  • "Closed" (ID: 100005) — Closed

También puedes pasar workflow_status_id directamente si ya conoces el ID.

Trabajar con el contexto "yo"

Cuando PRODUCTIVE_USER_ID está configurado, puedes usar "yo" en varias herramientas:

create_task con "assignee_id": "me"
update_task_assignment con "assignee_id": "me"
my_tasks para obtener tus tareas asignadas
whoami para verificar tu contexto de usuario configurado

Crear flujos de trabajo completos de tareas

Crear una carpeta: create_folder
Crear listas de tareas: create_task_list
Crear tareas: create_task
Desglosar el trabajo: create_subtask para subelementos, create_todo para listas de verificación
Agregar comentarios: add_task_comment
Actualizar estado: update_task_status con status_name (por ejemplo, "Abierto", "En espera", "Cerrado")
Seguimiento del progreso: Usa list_activities o get_recent_updates

Crear documentación

Crear una página raíz: create_page con project_id y title
Agregar páginas secundarias: create_page con parent_page_id y root_page_id establecido en la raíz
Anidar más profundamente: Establece parent_page_id en el padre y root_page_id en la página raíz
Reorganizar: Usa move_page para cambiar la página principal, copy_page para duplicar

Desarrollo

Ejecutar en modo de desarrollo: npm run dev
Compilar: npm run build
Iniciar el servidor compilado: npm start

Licencia

ISC