Productive.io MCP Server

An MCP (Model Context Protocol) server for Productive.io that enables AI assistants like Claude to interact with your Productive.io workspace — managing projects, tasks, time entries, budgets, and more.

Supports two transport modes:

• stdio (default) — Claude launches it as a local subprocess
• HTTP (with --http flag) — runs as an Express web server for remote/team use

Prerequisites

• Node.js 18+
• A Productive.io account with API access
• API Token — generate one in Productive.io under Settings → API integrations
• Organization ID — found in your Productive.io account settings

Installation

git clone <your-repo-url> productive-mcp-server
cd productive-mcp-server
npm install
cp .env.example .env
# Edit .env with your credentials
npm run build

Configuration

Variable	Required	Description
PRODUCTIVE_API_TOKEN	Yes	Your Productive.io API token
PRODUCTIVE_ORG_ID	Yes	Your Productive.io organization ID
PORT	No	HTTP server port (default: 3000)

Running

stdio mode (default — for local use)

# Development
npm run dev

# Production (after build)
npm start

HTTP mode (for remote/team use)

# Development
npm run dev:http

# Production (after build)
npm run start:http

The HTTP server exposes:

• POST /mcp — MCP protocol endpoint
• GET /health — health check

Connecting to Claude Desktop

Add this to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on 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"
      }
    }
  }
}

Connecting to Claude Code

stdio mode

claude mcp add productive -- node /absolute/path/to/productive-mcp-server/dist/index.js

Set the environment variables before running Claude Code, or add them to your shell profile:

export PRODUCTIVE_API_TOKEN=your_api_token_here
export PRODUCTIVE_ORG_ID=your_org_id_here

HTTP mode

Start the server first:

cd /path/to/productive-mcp-server
PRODUCTIVE_API_TOKEN=your_token PRODUCTIVE_ORG_ID=your_org npm run start:http

Then connect Claude Code:

claude mcp add productive --transport http http://localhost:3000/mcp

Connecting to VS Code

Add to your VS Code user settings JSON (.vscode/settings.json or user settings):

stdio mode

{
  "mcp": {
    "servers": {
      "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"
        }
      }
    }
  }
}

HTTP mode

{
  "mcp": {
    "servers": {
      "productive": {
        "type": "http",
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

Available Tools

Tool	Description	Key Parameters
productive_list_projects	List/search projects	company_id, project_type_id, status, query
productive_get_project	Get project by ID	id, include
productive_create_project	Create a project	name, project_type_id, company_id
productive_update_project	Update a project	id, name, project_type_id
productive_list_tasks	List/filter tasks	project_id, assignee_id, status, query
productive_get_task	Get task by ID	id, include
productive_create_task	Create a task	title, task_list_id, assignee_id
productive_update_task	Update a task	id, title, closed, assignee_id
productive_list_time_entries	List time entries	person_id, project_id, after, before
productive_log_time	Log a time entry	person_id, service_id, date, time
productive_list_people	List team members	status, company_id, query
productive_get_person	Get person by ID	id, include
productive_list_deals	List budgets/deals	project_id, company_id, deal_status
productive_get_deal	Get deal by ID	id, include
productive_list_companies	List companies	status, query
productive_get_company	Get company by ID	id, include
productive_list_bookings	List bookings	person_id, project_id, after, before
productive_list_services	List services	deal_id

Invoicing Tools (Draft Only)

All invoice tools create and manage draft invoices only. Finalization (assigning an invoice number) must always be done manually in the Productive.io UI.

Tool	Description	Key Parameters
productive_list_invoices	List/filter invoices	company_id, deal_id, invoice_status, date range
productive_get_invoice	Get full invoice details with line items	id
productive_create_invoice	Create a new empty draft invoice	company_id, document_type_id, subsidiary_id
productive_update_invoice	Update a draft invoice	id, subject, note, dates
productive_create_invoice_from_previous	Clone an invoice (line items + budget links)	source_invoice_id, optional overrides
productive_create_invoice_like_last_for_client	Clone a client's most recent invoice	company_id, how_many_back
productive_list_line_items	List line items for an invoice	invoice_id
productive_create_line_item	Add a line item to a draft invoice	invoice_id, description, quantity, unit_price, unit_id
productive_update_line_item	Update an existing line item	id, description, quantity, unit_price
productive_delete_line_item	Delete a line item	id
productive_list_invoice_attributions	List budget links for an invoice	invoice_id
productive_create_invoice_attribution	Link a draft invoice to a budget	invoice_id, deal_id, amount
productive_list_document_types	List available document types	subsidiary_id, status
productive_list_subsidiaries	List your company subsidiaries	status
productive_list_tax_rates	List available tax rates	status

All list tools support page, page_size, and sort parameters.

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

This opens an interactive UI to test each tool.

Rate Limits

Productive.io enforces:

• 100 requests per 10 seconds
• 4,000 requests per 30 minutes

The server implements automatic retry with exponential backoff for 429 responses (up to 3 retries).

License