Productive.io

You can access Productive.io data through a read-only MCP server that powers AI assistants with projects, tasks, pages, and teams information. It’s designed for efficiency, minimizing token use while exposing essential data for composing meaningful responses and automations.

How to use

Use an MCP client to connect to the Productive.io MCP Server and query data across projects, tasks, pages, comments, attachments, and more. The server returns streamlined results optimized for language models, including web links to view resources in Productive’s web interface. You can perform quick searches, view recent activity, and retrieve details about individual items like tasks or pages.

How to install

Prerequisites: Python 3.8 or newer. A Productive API token. A valid Productive organization ID.

Step 1: Obtain the source files by cloning or downloading the MCP server package.

# Clone the repository (URL to be provided by you)
git clone <repository-url>
cd productive-mcp

# Install dependencies
pip install -r requirements.txt

Step 2: Run the MCP server using Python directly or via UV as described in the configuration. Ensure you supply your API key and organization ID as environment variables.

# Direct Python execution (recommended)
PRODUCTIVE_API_KEY=<api-key> PRODUCTIVE_ORGANIZATION=<org-id> python server.py

# Using UV (UV must be installed)
export PRODUCTIVE_API_KEY=<api-key>
export PRODUCTIVE_ORGANIZATION=<org-id>
uv --directory <path-to-productive-mcp> run server.py

Configuration and runtime details

The server is configured via environment variables. You must provide your API key and organization ID. Optional settings include the API base URL and request timeout, plus the preferred tool output format.

Environment variables used by the server version shown include:

• PRODUCTIVE_API_KEY: Your Productive API token (required)

• PRODUCTIVE_ORGANIZATION: Your Productive organization ID (required)

• PRODUCTIVE_BASE_URL: Base URL for Productive API (default: https://api.productive.io/api/v2)

• PRODUCTIVE_TIMEOUT: Request timeout in seconds (default: 30)

• OUTPUT_FORMAT: Output format for tool responses ("toon" or "json", default: "toon")

Notes on usage and behavior

All tool responses are filtered for brevity and token efficiency. HTML is stripped from descriptions, empty or null values are removed, and webapp URLs are included for direct viewing in Productive.

Security and error handling

The MCP server uses HTTPS for all API requests. API tokens are loaded from environment variables and are never logged. If a request fails, the server returns standard MCP-like errors (e.g., Unauthorized, Not Found, Rate Limited, Server Error) with appropriate severity in logs.

Examples of common usage patterns

Search across content with quick_search to find projects, tasks, pages, or actions. Retrieve a specific task with get_task, including time tracking metrics. Obtain a summarized activity feed with get_recent_activity.

Available tools

get_projects

Retrieve all projects with basic information.

get_tasks

Retrieve tasks with optional filtering and pagination.

get_task

Retrieve a specific task by its internal ID, including time tracking metrics.

get_comments

Retrieve comments with optional filtering and pagination.

get_pages

Retrieve pages/documents with optional filtering and pagination.

get_page

Retrieve a specific page/document by ID.

get_attachments

Retrieve attachments/files with optional filtering and pagination.

get_todos

Retrieve todo checklist items with optional filtering and pagination.

get_todo

Retrieve a specific todo by ID.

get_recent_activity

Get a summarized feed of recent activities and updates.

quick_search

Fast, comprehensive search across projects, tasks, pages, and actions.

get_task_history

Retrieve the full history for a specific task including status and assignment history.

get_task_comments_summary

Provide a summary of comments and activity for a task.