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 (Model Context Protocol) que permite a Claude Desktop, Claude Code y otros clientes compatibles con MCP interactuar con la API de Productive.io.

Características

Resumen de tareas: get_task_overview devuelve todo sobre una tarea en una sola llamada, de modo que leer un issue 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 padre
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 correctas de estado de tareas
Seguimiento de tiempo: Lista y crea entradas de tiempo con integración de servicio/acuerdo
Contexto de usuario: Soporta 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

Obteniendo 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 la 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

Añade 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 añadir la configuración, reinicia Claude Desktop.

Uso con Claude Code

Añade 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 hacerlo de dos maneras:

Opción 1: Añade 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: Crea un script contenedor y añádelo 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
```

Añádelo 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 te han dado el ID

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

get_task_overview(task_id: "19300600")

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, de modo 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 9131629: Screenshot_2026-07-31_110620.png].
Indexados, en un bloque de ATTACHMENTS al final que lista cada adjunto de la tarea y de los comentarios mostrados, marcados con [IMAGE], con el comentario de origen y el autor.

Luego obtén solo los que importan con get_attachment(attachment_id: "9131629"), 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`	Obtiene el contexto del usuario actual y el ID de usuario configurado

Herramientas de empresas y proyectos

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

Herramientas de carpetas

Herramienta	Descripción
`list_folders`	Lista carpetas en un proyecto. Filtra por `project_id`, `status` (1=activo, 2=archivado), `limit`
`get_folder`	Obtiene detalles de una carpeta por `folder_id`
`create_folder`	Crea una carpeta. Requiere `project_id`, `name`
`update_folder`	Renombra una carpeta. Requiere `folder_id`, opcional `name`
`archive_folder`	Archiva una carpeta por `folder_id`
`restore_folder`	Restaura una carpeta archivada por `folder_id`

Herramientas de tableros y listas de tareas

Herramienta	Descripción
`list_boards`	Lista tableros. Filtra por `project_id`, `limit`
`create_board`	Crea un tablero. Requiere `project_id`, `name`
`list_task_lists`	Lista listas de tareas. Filtra por `board_id`, `limit`
`create_task_list`	Crea una lista de tareas. Requiere `board_id`, `project_id`, `name`
`get_task_list`	Obtiene detalles de una lista de tareas por `task_list_id`
`update_task_list`	Renombra una lista de tareas. Requiere `task_list_id`, opcional `name`
`archive_task_list`	Archiva una lista de tareas por `task_list_id`
`restore_task_list`	Restaura una lista de tareas archivada por `task_list_id`
`copy_task_list`	Copia una lista de tareas. Requiere `name`, `template_id`, `project_id`, `board_id`. Opcional `copy_open_tasks`, `copy_assignees`
`move_task_list`	Mueve una lista de tareas a otro tablero. Requiere `task_list_id`, `board_id`
`reposition_task_list`	Reordena 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 sola llamada devuelve metadatos, la descripción completa, los comentarios más recientes completos (10 por defecto, `comment_limit` hasta 50) del más antiguo al más reciente, y un índice de cada adjunto de la tarea y de esos comentarios. Requiere `task_id`
`list_tasks`	Lista tareas. Filtra por `project_id`, `assignee_id`, `status` (abierta/cerrada), `limit`
`get_project_tasks`	Obtiene todas las tareas de un proyecto. Requiere `project_id`, opcional `status`
`get_task`	Obtiene detalles de una tarea por `task_id`. Solo metadatos, sin comentarios. Prefiere `get_task_overview`
`create_task`	Crea una tarea. Requiere `title`. Opcional `project_id`, `board_id`, `task_list_id`, `assignee_id` (se admite "me"), `due_date`, `status`
`update_task_assignment`	Asigna/desasigna una tarea. Requiere `task_id`, `assignee_id` (se admite "me" o "null")
`update_task_details`	Actualiza título/descripción. Requiere `task_id`, opcional `title`, `description`, `description_html`
`update_task_status`	Establece el estado del 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, soporta estados personalizados
`delete_task`	Elimina una tarea por `task_id`
`my_tasks`	Obtiene las tareas asignadas a ti. Opcional `status`, `limit`
`reposition_task`	Reordena una tarea dentro de una lista
`update_task_sprint`	Mueve una tarea a un sprint/lista de tareas
`move_task_to_list`	Mueve una tarea a una lista de tareas diferente
`add_to_backlog`	Mueve una tarea al backlog

Herramientas de dependencias de tareas

Herramienta	Descripción
`list_task_dependencies`	Lista dependencias de una tarea. Filtra por `task_id` (lo que bloquea) o `dependent_task_id` (lo que la bloquea)
`get_task_dependency`	Obtiene detalles de una dependencia por `dependency_id`
`create_task_dependency`	Crea una dependencia. Requiere `task_id` (bloqueador), `dependent_task_id` (bloqueado). Opcional `type_id`: 1 = bloquea (por defecto), 2 = está bloqueada por, 3 = relacionada con
`delete_task_dependency`	Elimina una dependencia por `dependency_id`

Herramientas de subtareas

Herramienta	Descripción
`list_subtasks`	Lista subtareas de una tarea padre. Requiere `parent_task_id`, opcional `limit`
`create_subtask`	Crea 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`	Añade un comentario a una tarea. Requiere `task_id`, `comment` (soporta HTML y @menciones). Opcional `hidden` (booleano) publica un comentario interno no visible para los clientes en el portal de clientes
`list_comments`	Lista comentarios. Filtra 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`	Obtiene detalles completos de un comentario por `comment_id`
`update_comment`	Edita un comentario. Requiere `comment_id`, `body`
`delete_comment`	Elimina un comentario por `comment_id`
`pin_comment`	Fija un comentario por `comment_id`
`unpin_comment`	Desfija un comentario por `comment_id`
`add_comment_reaction`	Añade una reacción. Requiere `comment_id`, `reaction` (por ejemplo, "like")

Herramientas de todos

Herramienta	Descripción
`list_todos`	Lista todos en una tarea. Filtra por `task_id`, `status` (abierto/cerrado), `limit`
`get_todo`	Obtiene detalles de un todo por `todo_id`
`create_todo`	Crea un todo. Requiere `description`. Opcional `task_id`, `deal_id`, `assignee_id`, `due_date`
`update_todo`	Actualiza un todo. Requiere `todo_id`. Opcional `description`, `closed` (booleano), `due_date`
`delete_todo`	Elimina un todo por `todo_id`

Herramientas de páginas/documentos

Herramienta	Descripción
`list_pages`	Lista páginas. Filtra por `project_id`, `sort` (title/created_at/edited_at/updated_at), `limit`
`get_page`	Obtiene el contenido completo de una página por `page_id`
`create_page`	Crea una página. Requiere `project_id`, `title`. Opcional `body` (HTML), `parent_page_id`, `root_page_id`
`update_page`	Actualiza una página. Requiere `page_id`. Opcional `title`, `body`
`delete_page`	Elimina una página por `page_id`
`move_page`	Mueve una página bajo otra. Requiere `page_id`, `target_doc_id`
`copy_page`	Copia 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`
`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 — no necesitas buscar IDs:

update_task_status {
  "task_id": "12399194",
  "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: 102305) — Not Started
  • "Open" (ID: 102291) — Started
  • "On Hold" (ID: 102306) — Started
  • "Waiting" (ID: 102307) — Started
  • "Closed" (ID: 102292) — Closed

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

Trabajar con el Contexto "me"

Cuando PRODUCTIVE_USER_ID está configurado, puedes usar "me" 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 de Tareas Completos

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

Construir Documentación

Crear una página raíz: create_page con project_id y title
Agregar páginas hijas: create_page con parent_page_id y root_page_id establecido en la raíz
Anidar más profundo: Establece parent_page_id al padre y root_page_id a la página raíz
Reorganizar: Usa move_page para cambiar el padre de las páginas, 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