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