productive-mcp-rb2

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

1. Log in to Productive.io
2. Go to Settings → API integrations
3. Generate a new token
4. 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 | waiting_on | related). | | 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