Productive.io MCP服务器与CLI工具

Productive.io MCP Server & CLI

A Model Context Protocol (MCP) server and CLI tool that gives Claude (and other MCP-compatible AI clients) full access to your Productive.io account.

Ask Claude to create tasks, search projects, manage budgets, and more — through natural conversation via MCP, or directly via the productive CLI.

Features

• Task Management - Create, search, update, and bulk-create tasks
• Task List Management - Full CRUD: create, rename, archive, restore, delete, reposition, move, copy
• Project Discovery - List and search projects, boards, and team members
• Budget Management - List, update, audit, close budgets; mark as delivered
• Revenue Distributions - Create, update, extend, and report on revenue distributions
• Service Management - Manage services (budget line items) and service types
• Task Dependencies - Create blocking, waiting-on, and related dependencies
• Pages & Comments - Create and manage documentation pages and task comments
• Attachments - Upload and list file attachments on tasks
• Checklists - Create and manage to-do items on tasks
• Rate Limiting - Automatic handling of Productive.io's API rate limits
• Flexible Output - Both Markdown and JSON response formats

Quick Start

Prerequisites

• Node.js 18+
• A Productive.io account with API access

1. Install

npm install

2. Add your credentials

cp .env.example .env

Edit .env and fill in two values:

• API Token - from Productive.io → Settings → Integrations → API → Generate a token
• Organisation ID - the number in your Productive URL: https://app.productive.io/{ORG_ID}/...

3. Run auto-setup

npm run setup

This connects to your Productive account, discovers your custom fields and workflow statuses, and writes a productive.config.json file. No manual API calls or source code editing needed.

4. Build

npm run build

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "productive": {
      "command": "node",
      "args": ["/absolute/path/to/productive-mcp-server/dist/index.js"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_org_id_here"
      }
    }
  }
}

Connect to Claude Code

There are two ways to use this project with Claude Code: the CLI (recommended) and MCP.

Option A: CLI (recommended)

The CLI gives Claude Code direct shell access to all 70+ Productive tools via the Bash tool, which is faster and more reliable than MCP for Claude Code.

1. Make the CLI available globally:

npm link

This creates a global productive command. Alternatively, use node /absolute/path/to/productive-mcp-server/dist/cli.js directly.

2. Set environment variables:

The CLI reads PRODUCTIVE_API_TOKEN and PRODUCTIVE_ORG_ID from the environment. Add them to your shell profile (e.g. ~/.zshrc):

export PRODUCTIVE_API_TOKEN="your_api_token_here"
export PRODUCTIVE_ORG_ID="your_org_id_here"

3. Verify:

productive list-projects --limit 3
productive search-tasks --query "bug" --limit 5
productive --help

4. Tell Claude Code about it:

Add to your project's CLAUDE.md or ~/.claude/CLAUDE.md:

## Productive.io CLI

Use the `productive` CLI to interact with Productive.io. Run `productive --help` for all commands, or `productive <command> --help` for options.

Examples:

- `productive search-tasks --project_id 123 --limit 10`
- `productive create-task --title "Fix bug" --project_id 123 --task_list_id 456`
- `productive get-task --task_id 789`
- `productive create-page --title "Notes" --body @notes.md --project_id 123`

Claude Code will then use the CLI via Bash tool calls automatically when you ask it to interact with Productive.

Option B: MCP

If you prefer MCP (or want both), add the server to Claude Code:

Via CLI (recommended):

claude mcp add --scope user productive -t stdio \
  -e PRODUCTIVE_API_TOKEN=your_api_token_here \
  -e PRODUCTIVE_ORG_ID=your_org_id_here \
  -- node /absolute/path/to/productive-mcp-server/dist/index.js

Via config file:

Add to .claude/settings.json or ~/.claude.json:

{
  "mcpServers": {
    "productive": {
      "command": "node",
      "args": ["/absolute/path/to/productive-mcp-server/dist/index.js"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_org_id_here"
      }
    }
  }
}

Verify

Restart Claude and ask: "List my projects in Productive"

CLI Usage

The productive CLI mirrors all MCP tools as subcommands. The tool name productive_search_tasks becomes search-tasks:

# Search and filter
productive search-tasks --project_id 123 --limit 5
productive search-tasks --query "bug" --sort -created_at
productive list-projects --format markdown

# Create and update
productive create-task --title "Fix bug" --project_id 123 --task_list_id 456
productive update-task --task_id 789 --workflow_status "In Progress"

# Long content via @file (reads file contents into the argument)
productive create-page --title "Design Doc" --body @design.md --project_id 123
productive update-task --task_id 789 --description @description.html

# Pipe from stdin with @-
echo "# Meeting Notes" | productive create-page --title "Notes" --body @- --project_id 123

# Comma-separated arrays
productive create-task --title "Urgent fix" --labels "Bug,Urgent" --project_id 123 --task_list_id 456

# JSON for complex nested args (e.g. batch creation)
productive create-tasks-batch --project_id 123 --task_list_id 456 --tasks @tasks.json

Output format

JSON by default (machine-readable, ideal for Claude Code). Use --format markdown for human-readable output:

productive get-task --task_id 123                    # JSON output
productive get-task --task_id 123 --format markdown  # Markdown output

Help

productive --help                    # List all commands
productive search-tasks --help       # Show options for a specific command

Custom Field Configuration

Productive.io uses custom fields for task type, priority, estimates, and (optionally) a free-text Commit reference such as IT-204 that teams use in branch names and commit messages. Tasks expose it as commit_reference, and search-tasks --commit_reference IT-204 finds a task by it. These field IDs are unique to each organisation.

The recommended approach is npm run setup which auto-discovers everything. The generated productive.config.json file is loaded at runtime - no source code editing or rebuilding needed after setup.

If auto-detection doesn't find your fields (they may be named differently), you can edit productive.config.json manually. The setup script will list all available custom fields in your account to help you identify the right ones.

The server works without custom field configuration - you just won't be able to set task types, priorities, or workflow statuses through Claude. With no config the workflow_status parameter is omitted from the tools entirely, so task creation still works; passing a status explicitly returns an error pointing at the setup script rather than being silently ignored.

Productive scopes statuses to a workflow, and most organisations have an unused Default workflow alongside the one they work in - which means duplicate status names with different IDs. Setup detects which workflow your tasks actually use and resolves duplicates in its favour. See docs/workflow-statuses.md for how this resolves, why a name may be refused, and the known limitation for organisations genuinely running two workflows.

Available Tools

Task Management

Task Templates

Templates are JSON files in templates/ describing a standard set of task lists, tasks and subtasks (e.g. the core delivery tickets for a new project), with {{variable}} placeholders filled in at apply time. See docs/templates.md. Run npm run templates:report for an interactive preview of what each template (or a stack of them) creates.

Project & Organisation

Task Lists

Budgets

Revenue Distributions

Services

Estimate vs Quantity. A service's Estimate (the "Estimate" column in a deal's Services view) is the planned time, stored by Productive as estimated_time in minutes. Quantity is the billable quantity and affects revenue: on Fixed hourly services it drives budgeted_time and the deal value, so don't use it to record time estimates. Set the estimate on create or update with estimated_time_minutes (whole minutes) or estimated_time_hours (rounded to the nearest minute), but not both:

productive update-service --service_id 12345 --estimated_time_minutes 6187   # 103h 7m
productive update-service --service_id 12345 --estimated_time_hours 103.12   # also 6187

Get and list responses return estimated_time (minutes) and estimated_time_hours (2 decimal places) in JSON, and an Estimate line in markdown.

Dependencies

Pages, Comments & Attachments

Development

npm run dev      # Watch mode with auto-reload
npm run build    # Compile TypeScript
npm start        # Run compiled MCP server
npm run cli      # Run CLI (or `productive` after npm link)
npm run clean    # Remove build artifacts

Licence

MIT