Productive.io MCP Server

An MCP (Model Context Protocol) server that enables Claude Desktop, Claude Code, and other MCP-compatible clients to interact with the Productive.io API.

Features

• Companies & Projects: List companies and projects with status filtering
• Task Management: List, create, and get individual tasks with various filters
• Task Operations: Add comments to tasks and update task status via workflow statuses
• Board & Task List Management: Create and manage boards and task lists within projects
• People Management: List people in your organization with filtering options
• Workflow Management: List and work with workflow statuses for proper task status updates
• User Context: Supports "me" references when PRODUCTIVE_USER_ID is configured
• Activity Tracking: View activities and recent updates across your organization

Installation

Via npm (Recommended)

Install globally:

npm install -g productive-mcp

Or run directly with npx (no installation required):

npx productive-mcp

From Source

1. Clone this repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Configuration

Getting Your Credentials

To obtain your Productive.io credentials:

1. Log in to Productive.io
2. Go to Settings → API integrations
3. Generate a new token (choose read-only for safety, or full access for task creation)
4. Copy the token and organization ID

To find your user ID:

• You can use the API to list people and find your ID
• Or check the URL when viewing your profile in Productive.io

Environment Variables

The server requires the following environment variables:

Variable	Required	Description
PRODUCTIVE_API_TOKEN	Yes	Your Productive.io API token
PRODUCTIVE_ORG_ID	Yes	Your organization ID
PRODUCTIVE_USER_ID	No	Your user ID (required for my_tasks tool)

Usage with Claude Desktop

Add the server to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended)

{
  "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"
      }
    }
  }
}

Using Global Installation

{
  "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"
      }
    }
  }
}

Using Local Build

{
  "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"
      }
    }
  }
}

Note: PRODUCTIVE_USER_ID is optional but required for the my_tasks tool to work.

After adding the configuration, restart Claude Desktop.

Usage with Claude Code

Add the server to your Claude Code configuration using the CLI:

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

Then set your environment variables. You can either:

Option 1: Add to your shell profile (~/.zshrc or ~/.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"

Option 2: Create a wrapper script and add it as an MCP server:

1. Create a script file (e.g., ~/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

2. Make it executable:

   chmod +x ~/scripts/productive-mcp.sh

3. Add to Claude Code:

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

Option 3: Edit the Claude Code settings file directly at ~/.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"
      }
    }
  }
}

Restart Claude Code after configuration.

Available Tools

User & Context Tools

whoami

Get the current user context and check which user ID is configured for "me" operations.

Company & Project Tools

list_companies

Get a list of companies/customers from Productive.io

Parameters:

• status (optional): Filter by company status ('active' or 'archived')
• limit (optional): Number of companies to return (1-200, default: 30)

list_projects

Get a list of projects from Productive.io

Parameters:

• status (optional): Filter by project status ('active' or 'archived')
• company_id (optional): Filter projects by company ID
• limit (optional): Number of projects to return (1-200, default: 30)

Board & Task List Tools

list_boards

Get a list of boards from projects

Parameters:

• project_id (optional): Filter boards by project ID
• limit (optional): Number of boards to return (max 200, default: 30)

create_board

Create a new board in a Productive.io project

Parameters:

• project_id (required): The ID of the project to create the board in
• name (required): Name of the board
• description (optional): Description of the board

list_task_lists

Get a list of task lists from boards

Parameters:

• board_id (optional): Filter task lists by board ID
• limit (optional): Number of task lists to return (max 200, default: 30)

create_task_list

Create a new task list in a board

Parameters:

• board_id (required): The ID of the board to create the task list in
• project_id (required): The ID of the project
• name (required): Name of the task list
• description (optional): Description of the task list

Task Management Tools

list_tasks

Get a list of tasks from Productive.io

Parameters:

• project_id (optional): Filter tasks by project ID
• assignee_id (optional): Filter tasks by assignee ID
• status (optional): Filter by task status ('open' or 'closed')
• limit (optional): Number of tasks to return (1-200, default: 30)

get_project_tasks

Get all tasks for a specific project

Parameters:

• project_id (required): The ID of the project
• status (optional): Filter by task status ('open' or 'closed')

get_task

Get detailed information about a specific task

Parameters:

• task_id (required): The ID of the task to retrieve

create_task

Create a new task in Productive.io

Parameters:

• title (required): Task title
• description (optional): Task description
• project_id (optional): ID of the project to add the task to
• board_id (optional): ID of the board to add the task to
• task_list_id (optional): ID of the task list to add the task to
• assignee_id (optional): ID of the person to assign (use "me" for configured user)
• due_date (optional): Due date in YYYY-MM-DD format
• status (optional): Task status ('open' or 'closed', default: 'open')

update_task_assignment

Update the assignee of an existing task

Parameters:

• task_id (required): ID of the task to update
• assignee_id (required): ID of the person to assign (use "me" for configured user, "null" to unassign)

my_tasks

Get tasks assigned to you (requires PRODUCTIVE_USER_ID to be configured)

Parameters:

• status (optional): Filter by task status ('open' or 'closed')
• limit (optional): Number of tasks to return (1-200, default: 30)

Task Operations Tools

add_task_comment

Add a comment to a task

Parameters:

• task_id (required): ID of the task to add the comment to
• comment (required): Text content of the comment

update_task_status

Update the status of a task using workflow status ID

Parameters:

• task_id (required): ID of the task to update
• workflow_status_id (required): ID of the workflow status to set

list_workflow_statuses

List workflow statuses available in Productive.io (used for task status updates)

Parameters:

• workflow_id (optional): Filter by workflow ID
• category_id (optional): Filter by category (1=Not Started, 2=Started, 3=Closed)
• limit (optional): Number of statuses to return (1-200, default: 50)

People Management Tools

list_people

List people in the organization with optional filters

Parameters:

• company_id (optional): Filter people by company ID
• project_id (optional): Filter people assigned to a specific project
• is_active (optional): Filter by active status
• email (optional): Filter by email address
• limit (optional): Maximum number of people to return (default: 50, max: 100)
• page (optional): Page number for pagination (default: 1)

get_project_people

Get all people assigned to a specific project

Parameters:

• project_id (required): The project ID to get people for
• is_active (optional): Filter by active status (default: true)
• limit (optional): Maximum number of people to return (default: 50, max: 100)
• page (optional): Page number for pagination (default: 1)

Activity & Updates Tools

list_activities

List activities and changes across your organization

Parameters:

• task_id (optional): Filter activities by task ID
• project_id (optional): Filter activities by project ID
• person_id (optional): Filter activities by person ID
• item_type (optional): Filter by item type
• event (optional): Filter by event type
• after (optional): Filter activities after this date (ISO 8601 format)
• before (optional): Filter activities before this date (ISO 8601 format)
• limit (optional): Number of activities to return
• page (optional): Page number for pagination

get_recent_updates

Get recent updates and activities in a summarized format

Parameters:

• limit (optional): Number of recent updates to return (default: 20)
• hours (optional): Number of hours to look back (default: 24)

Common Workflows

Updating Task Status

To update a task's status, you need to use workflow status IDs rather than simple "open"/"closed" values:

1. First, list available workflow statuses:

   list_workflow_statuses
   

   This will show you all available statuses with their IDs and categories (Not Started=1, Started=2, Closed=3).

2. Then update the task status:

   update_task_status {
     "task_id": "12399194",
     "workflow_status_id": "specific_status_id_from_step_1"
   }
   

Working with "me" Context

When PRODUCTIVE_USER_ID is configured, you can use "me" in several tools:

• create_task with "assignee_id": "me"
• update_task_assignment with "assignee_id": "me"
• my_tasks to get your assigned tasks
• whoami to verify your configured user context

Creating Complete Task Workflows

1. Create a board: create_board
2. Create task lists: create_task_list
3. Create tasks: create_task
4. Add comments: add_task_comment
5. Update status: Use list_workflow_statuses then update_task_status
6. Track progress: Use list_activities or get_recent_updates

Development

• Run in development mode: npm run dev
• Build: npm run build
• Start built server: npm start

License

ISC