productive-mcp-rb2

npm version

An MCP (Model Context Protocol) server for Productive.io, extended with delivery-focused tools for budget burn, resource planning, and org overview.

Based on berwickgeek/productive-mcp — extended by Ruben Langeweg.

Quick Start

1. Get your credentials

Log in to Productive.io
Go to Settings → API integrations
Generate a new token
Note your API token and Organisation ID

To find your user ID: use the whoami tool after setup, or check your profile URL in Productive.io.

2. Configure your MCP host

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "productive": {
      "command": "npx",
      "args": ["-y", "productive-mcp-rb2"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token",
        "PRODUCTIVE_ORG_ID": "your_org_id",
        "PRODUCTIVE_USER_ID": "your_user_id"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

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

Then set your environment variables in ~/.zshrc or ~/.bashrc:

export PRODUCTIVE_API_TOKEN="your_api_token"
export PRODUCTIVE_ORG_ID="your_org_id"
export PRODUCTIVE_USER_ID="your_user_id"

3. Try it

Once configured, ask your AI assistant:

"Show me my open tasks"
"Log 2 hours to the Gadero project for today"
"Which projects are over 80% budget burn?"
"Mark task 99 as Done"

Environment Variables

Variable	Required	Description
`PRODUCTIVE_API_TOKEN`	Yes	Your Productive.io API token
`PRODUCTIVE_ORG_ID`	Yes	Your organisation ID
`PRODUCTIVE_USER_ID`	Optional	Your user ID — enables `my_tasks`, `me` shorthand in all tools, and the `productive://me/*` resources

Installation

Via npx (no install required)

npx productive-mcp-rb2

Global install

npm install -g productive-mcp-rb2

Updating

npx users — no action needed. Restart your MCP host and npx resolves the latest published version.

Global install users:

npm install -g productive-mcp-rb2@latest

Local checkout users:

git pull && npm install && npm run build

Then restart your MCP host.

Automated npm publishing

This repo includes .github/workflows/npm-publish.yml.

Trigger: every push to main
Guardrail: skips publishing if the current package.json version already exists on npm
Auth: requires repository secret NPM_TOKEN

Typical release flow:

npm version patch
git push

Tool Reference

Tools are listed in tables, grouped by area. Read-only tools are safe to call freely; write/mutate tools are noted in the description.

People & Identity

Tool	Description
`whoami`	Get the current user context — shows which user ID is configured as "me".
`list_people`	List team members. Optional `company_id`, `project_id`, `is_active`, `email`, `limit`.
`get_person`	Get details about a person. Requires `person_id`.

Projects & Companies

Tool	Description
`list_projects`	List projects in your organisation. Optional `status`, `company_id`, `limit`.
`list_companies`	List companies (clients). Optional `status`, `limit`.

Tasks

Tool	Description
`list_tasks`	List tasks. Optional `project_id`, `assignee_id`, `status`, `limit`.
`get_task`	Get full details of a task. Requires `task_id`.
`get_project_tasks`	Get all tasks for a project. Requires `project_id`. Optional `status`.
`my_tasks`	Get tasks assigned to the configured user. Requires `PRODUCTIVE_USER_ID`.
`create_task`	Create a task. Requires `title`. Optional `description`, `project_id`, `board_id`, `task_list_id`, `assignee_id` (use `"me"`), `due_date`, `status`.
`update_task_details`	Update title and/or description. Requires `task_id`. Optional `title`, `description`.
`update_task_assignment`	Set or clear a task's assignee. Requires `task_id`, `assignee_id` (use `"me"` or `"null"`).
`update_task_status`	Set task status by `workflow_status_id` OR `status_name` (case-insensitive, partial match). Requires `task_id`.
`update_task_sprint`	Move task to one or more sprints (custom field). Requires `task_id`.
`reposition_task`	Reposition a task within its list. Requires `taskId`. Optional `move_before_id`, `move_after_id`.
`move_task_to_list`	Move a task to a different task list. Requires `task_id`, `task_list_id`.
`add_to_backlog`	Add a task to the project backlog. Creates a Backlog list if missing. Requires `task_id`.
`create_tasks_batch`	Create multiple tasks at once. Requires `tasks` array.
`delete_task`	Permanently delete a task. Destructive. Requires `task_id`.

Subtasks

Tool	Description
`list_subtasks`	List child tasks of a parent. Requires `parent_task_id`. Optional `limit`.
`create_subtask`	Create a subtask under a parent. Requires `parent_task_id`, `title`. Optional `project_id`, `task_list_id`, `assignee_id` (use `"me"`), `due_date`, `description`.

Task Todos / Checklists

Tool	Description
`list_todos`	List checklist items on a task. Requires `task_id`.
`get_todo`	Get a single todo. Requires `todo_id`.
`create_todo`	Add a checklist item. Requires `task_id`, `title`.
`update_todo`	Rename a todo or toggle completed. Requires `todo_id`. Optional `title`, `completed`.
`delete_todo`	Delete a checklist item. Destructive. Requires `todo_id`.

Task Dependencies

Tool	Description
`list_task_dependencies`	List dependencies for a task. Requires `task_id`.
`get_task_dependency`	Get a single dependency by ID. Requires `dependency_id`.
`add_task_dependency`	Link two tasks. Requires `task_id`, `depends_on_task_id`. Optional `type` (`blocking`
`remove_task_dependency`	Remove a dependency by its ID. Destructive. Requires `dependency_id`.

Comments

Tool	Description
`list_comments`	List comments on a task. Requires `task_id`. Optional `project_id`, `limit`.
`get_comment`	Get a comment by ID. Requires `comment_id`.
`add_task_comment`	Add a comment to a task. Requires `task_id`, `comment`.
`update_comment`	Edit a comment's body. Requires `comment_id`, `body`.
`pin_comment`	Pin a comment to the top. Requires `comment_id`.
`unpin_comment`	Unpin a comment. Requires `comment_id`.
`add_comment_reaction`	Add a reaction (e.g. `like`). Requires `comment_id`, `reaction`.
`delete_comment`	Delete a comment. Destructive. Requires `comment_id`.

Attachments

Tool	Description
`list_attachments`	List file attachments on a task or comment. Requires `task_id` or `comment_id`.

Boards & Task Lists

Tool	Description
`list_boards`	List boards in a project.
`create_board`	Create a board. Requires `project_id`, `name`.
`list_task_lists`	List task lists. Optional `board_id`, `limit`.
`get_task_list`	Get a single task list. Requires `task_list_id`.
`create_task_list`	Create a task list. Requires `board_id`, `project_id`, `name`.
`update_task_list`	Rename a task list. Requires `task_list_id`, `name`.
`archive_task_list`	Archive a task list (reversible). Requires `task_list_id`.
`restore_task_list`	Restore an archived task list. Requires `task_list_id`.
`reposition_task_list`	Reposition a task list. Requires `task_list_id`. Optional `move_before_id`.

Folders

Folders group boards within a project.

Tool	Description
`list_folders`	List folders. Optional `project_id`, `status` (1=active, 2=archived), `limit`.
`get_folder`	Get a single folder. Requires `folder_id`.
`create_folder`	Create a folder. Requires `project_id`, `name`.
`update_folder`	Rename a folder. Requires `folder_id`, `name`.
`archive_folder`	Archive a folder (reversible). Requires `folder_id`.
`restore_folder`	Restore an archived folder. Requires `folder_id`.

Workflow Statuses

Tool	Description
`list_workflow_statuses`	List workflow statuses. Optional `workflow_id`, `category_id` (1=Not Started, 2=Started, 3=Closed), `limit`.

Time Entries

Time entry creation follows a 5-step workflow: project → deal → service → task → create.

Tool	Description
`list_time_entries`	View existing time entries. Optional `date`, `after`, `before`, `person_id` (use `"me"`), `project_id`, `limit`.
`create_time_entry`	Create a time entry (step 5 of the workflow). Requires `service_id`, `time`, `date`, `note` (≥10 chars).
`update_time_entry`	Update an existing time entry. Requires `time_entry_id`. Optional `time`, `note`, `date`.
`delete_time_entry`	Delete a time entry. Destructive. Requires `time_entry_id`.
`list_services`	List all services in the org.
`list_project_deals`	List deals/budgets for a project (step 2). Requires `project_id`.
`list_deal_services`	List services for a deal (step 3). Requires `deal_id`.
`get_project_services`	Convenience: get services for a project across all deals. Requires `project_id`.

Memberships

Tool	Description
`list_memberships`	List project/team memberships. Optional `project_id`, `person_id`, `limit`.

Expenses

Tool	Description
`list_expenses`	List expenses. Optional `person_id` (use `"me"`), `project_id`, `after`, `before`, `limit`.
`create_expense`	Log an expense. Requires `date`, `amount`. Optional `project_id`, `deal_id`, `note`, `billable`.

Invoices

Tool	Description
`list_invoices`	List invoices. Optional `company_id`, `project_id`, `status`, `after`, `before`, `limit`.
`get_invoice`	Get a single invoice. Requires `invoice_id`.

Activity & Pages

Tool	Description
`list_activities`	List activities (changes/updates). Optional `project_id`, `person_id`, date range, `limit`.
`get_recent_updates`	Summary of recent updates with breakdown by item type. Optional `days`.
`list_pages`	List knowledge base pages. Optional `project_id`, `limit`.
`get_page`	Get full content of a page. Requires `page_id`.
`create_page`	Create a new page. Requires `project_id`, `title`. Optional `body` (HTML), `parent_page_id`.
`update_page`	Update title and/or body. Requires `page_id`. Optional `title`, `body`.
`move_page`	Move a page under another parent. Requires `page_id`, `target_doc_id`.
`copy_page`	Copy a page from a template. Requires `template_id`. Optional `project_id`.
`delete_page`	Delete a page. Destructive. Requires `page_id`.

rb2 Delivery Tools

These tools are extended beyond the core Productive.io API and are tailored for rb2's delivery workflow.

Tool	Description
`get_budget_burn`	Budget burn analysis with RAG status (Green <70%, Amber 70-90%, Red >90%). Optional `min_burn_pct`, `project_id`.
`get_resource_plan`	Team bookings and utilisation for a date range. Optional `person_name`, `project_id`, `after`, `before`.
`get_overbooked_people`	Detect team members exceeding capacity. Optional `threshold_pct`, `after`, `before`.
`get_org_overview`	rb2 headcount per subsidiary (NL, SCAPE, Code Blue, CN, PT, NG) with active project counts.
`list_bookings`	Raw resource bookings/capacity entries. Optional `person_id` (use `"me"`), `project_id`, date range.

Common Workflows

Updating task status by name

update_task_status accepts a status_name instead of an ID — it auto-resolves against the project's workflow statuses (case-insensitive, partial match).

"Move task 12345 to In Progress"
   → update_task_status(task_id="12345", status_name="In Progress")

If the name is ambiguous or missing, the tool returns the available statuses so you can retry with workflow_status_id.

Creating a subtask

"Add a subtask 'Write tests' under task 12345 assigned to me"
   → create_subtask(parent_task_id="12345", title="Write tests", assignee_id="me")

Logging time (5-step flow)

list_projects
   → list_project_deals(project_id)
      → list_deal_services(deal_id)
         → get_project_tasks(project_id)         # optional, to link a task
            → create_time_entry(service_id, time, date, note)

The simplest approach is to use the timesheet prompt, which walks through every step automatically.

Managing knowledge base pages

"Create a runbook for project 12345 with the deployment steps"
   → create_page(project_id="12345", title="Deployment Runbook", body="<p>...</p>")

"Move page 999 under page 100"
   → move_page(page_id="999", target_doc_id="100")

Pinning an important comment

list_comments(task_id) → pick the comment ID → pin_comment(comment_id)

Prompts (5 total)

Prompts are pre-built workflow templates that guide the AI through multi-step operations. Invoke them by name in Claude Desktop or with /mcp__productive__<name> in Claude Code.

`timesheet`

Guided workflow for creating timesheet entries. Walks through project → budget → service → task → time entry selection with proper validation. Accepts optional hints to pre-fill the workflow.

Arguments:

project — project name or ID to start with (optional)
date — today, yesterday, or YYYY-MM-DD (optional)
time — duration like "2h", "120m", "1.5h" (optional)
work_description — brief description of work performed (optional)

`quick_timesheet`

Step-by-step guidance for a specific stage of the timesheet workflow. Use when you're already partway through and need help with a specific step: project, budget, service, task, or create.

Arguments:

step — current step: project, budget, service, task, or create
project_id — project ID if already selected (optional)
deal_id — deal/budget ID if already selected (optional)
service_id — service ID if already selected (optional)
task_id — task ID if already selected (optional)

`weekly_report`

Generate a structured weekly status report for a team member: time logged, tasks completed, in-progress work.

Arguments:

person_id — person to report on (leave blank to use the configured user)
week_start — start of the week in YYYY-MM-DD format (defaults to current Monday)

`project_health`

Full project health check: budget burn, open tasks, team capacity, and recent activity — produces a RAG-rated summary.

Arguments:

project_id — the Productive.io project ID to analyse

`sprint_planning`

Walk through sprint planning: review backlog, check capacity, select tasks, create new ones, and assign the team.

Arguments:

project_id — the project ID to plan the sprint for
sprint_name — name for the new sprint (e.g. "Sprint 12")

Resources (6 total)

Resources are read-only data sources you can reference directly. In Claude, prefix with @productive or use the URI scheme productive://.

Resource	Description
`productive://projects`	All active projects in Productive.io — names, IDs, and status.
`productive://org/overview`	rb2 headcount per subsidiary and total active projects.
`productive://me/tasks`	Open tasks assigned to the configured user. Requires `PRODUCTIVE_USER_ID`.
`productive://me/today`	Time entries logged today by the configured user. Requires `PRODUCTIVE_USER_ID`.
`productive://projects/{id}/tasks` (template)	Open tasks for a specific project. Replace `{id}`.
`productive://tasks/{id}` (template)	Full details of a specific task. Replace `{id}`.

Timesheet Workflow

The recommended workflow for logging time follows a strict hierarchy:

list_projects
    ↓
list_project_deals       (get budgets for the project)
    ↓
list_deal_services       (get services for the budget)
    ↓
list_tasks               (optional: find task to link)
    ↓
create_time_entry        (log time with service_id + notes)

The simplest approach is to use the timesheet prompt, which walks through all steps automatically.

Repository

github.com/rubenlangeweg/productive-mcp

License

ISC

productive-mcp-rb2

Quick Start

1. Get your credentials

2. Configure your MCP host

Claude Desktop

Claude Code

3. Try it

Environment Variables

Installation

Via npx (no install required)

Global install

Updating

Automated npm publishing

Tool Reference

People & Identity

Projects & Companies

Tasks

Subtasks

Task Todos / Checklists

Task Dependencies

Comments

Attachments

Boards & Task Lists

Folders

Workflow Statuses

Time Entries

Memberships

Expenses

Invoices

Activity & Pages

rb2 Delivery Tools

Common Workflows

Updating task status by name

Creating a subtask

Logging time (5-step flow)

Managing knowledge base pages

Pinning an important comment

Prompts (5 total)

timesheet

quick_timesheet

weekly_report

project_health

sprint_planning

Resources (6 total)

Timesheet Workflow

Repository

License

Latest Blog Posts

MCP directory API

`timesheet`

`quick_timesheet`

`weekly_report`

`project_health`

`sprint_planning`