productive-mcp
productive-mcp is an MCP server for Productive.io that lets you manage time tracking, projects, people, and reporting through natural language commands.
Time Tracking:
Log time entries on a project with optional notes, date, and service hints
List time entries filtered by date range, project, or owner (defaults to your own entries)
Update existing time entries (hours, date, note, or service)
Permanently delete time entries
Project & Service Management:
List all active projects; fuzzy-search by partial name or number
List services (billable activity types) for a given project
Set or override the default service remembered for a project to streamline logging
People Search:
Fuzzy-search team members by name or email
Reporting & Briefings:
Generate time reports with categorized summaries (worked, client, internal, holidays)
Retrieve hours summaries for any team member
Get a personal weekly briefing with total hours and per-project breakdown
View projects on which you've recently logged time
Smart Features:
Fuzzy matching for projects and people supports natural input
Billing-cutoff-aware period resolution (e.g. adjusts "this month" based on your invoicing cycle)
Local cache for projects, people, and services with manual refresh option
Token-Optimized Output (TOON) mode for reduced token usage
Abstracts Productive.io's internal minute-based tracking — interact in hours only
Secure credential storage via OS keychain, Credential Manager, Secret Service, or environment variables
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@productive-mcp log 3 hours on the Q4 marketing campaign project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
productive-mcp
An MCP server for Productive.io — log time, inspect projects, manage entries, and get team reports from any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) using plain English:
"log 2.5 hours on the Acme security review project"
"how many hours did Alice log this week?"
"give me my weekly briefing"
Built around the Productive.io JSON:API v2 with fuzzy project and person matching, a local disk cache, billing-cutoff-aware period resolution, and per-project default-service memory.
Features
14 tools covering projects, people, services, time entries, reports, and briefings
Cross-platform credential storage — macOS Keychain, Windows Credential Manager (DPAPI/TPM-backed), Linux Secret Service, or environment variables
Fuzzy matching for projects and people —
"Acme","1099 Acme","Alice", or"me"all resolve naturallyBilling-cutoff-aware period resolution —
"this_month"shifts based on your invoicing cycleRemembers your default service per project so you don't have to specify it every time
Local cache for projects, people, and services (1-hour TTL, manually refreshable)
TOON output mode — optional token-optimised encoding for 30–60% fewer tokens
hoursin,hoursout — the API uses minutes internally, but you never see themScoped to "me" by default —
list_time_entriesonly shows your own entries unless you opt out
Related MCP server: Work-Timer
Requirements
Python 3.11+
A Productive.io account with API access enabled
macOS, Windows, or Linux
Install
1. Clone and install
git clone https://github.com/cameronfairbairn/productive-mcp.git
cd productive-mcp
uv venv
uv pip install -e .(or python -m venv .venv && .venv/bin/pip install -e . if you don't use uv)
2. Get your Productive credentials
You need three values:
Value | Where to find it |
API token | Productive → Settings → API integrations → Generate new token |
Organization ID | The numeric segment in your Productive URL: |
Person ID | Your own user ID — open your profile in Productive; it's the numeric segment in the URL |
3. Store credentials
Option A — OS credential store (recommended)
Works on any platform via the keyring library:
python -c "import keyring; keyring.set_password('productive-mcp', 'token', '<token>')"
python -c "import keyring; keyring.set_password('productive-mcp', 'org_id', '<org_id>')"
python -c "import keyring; keyring.set_password('productive-mcp', 'person_id', '<person_id>')"Platform | Backend | Security |
macOS | Keychain | Secure Enclave where available |
Windows | Credential Manager (DPAPI) | TPM-backed on TPM 2.0 systems |
Linux (desktop) | Secret Service (GNOME Keyring / KWallet) | Session-encrypted |
On macOS, the security CLI also works (keyring reads from the same Keychain):
security add-generic-password -s productive-mcp -a token -w "<token>" -U
security add-generic-password -s productive-mcp -a org_id -w "<org_id>" -U
security add-generic-password -s productive-mcp -a person_id -w "<person_id>" -UOption B — environment variables (CI / headless / override)
export PRODUCTIVE_MCP_TOKEN="<token>"
export PRODUCTIVE_MCP_ORG_ID="<org_id>"
export PRODUCTIVE_MCP_PERSON_ID="<person_id>"Environment variables take precedence over the credential store.
4. Register the server with your MCP client
Claude Code (~/.claude.json)
{
"mcpServers": {
"productive": {
"type": "stdio",
"command": "/path/to/productive-mcp/.venv/bin/productive-mcp",
"args": []
}
}
}Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"productive": {
"command": "/path/to/productive-mcp/.venv/bin/productive-mcp"
}
}
}Restart the client after editing its config.
5. (Optional) Global install with the bundled deploy script
bash scripts/install.shThis creates ~/.local/share/productive-mcp/ containing a fresh venv and a run.sh launcher. Point your MCP client at ~/.local/share/productive-mcp/run.sh instead. Re-running the script upgrades in place.
Tools
All tools are prefixed with productive_ so they namespace cleanly alongside other MCP servers.
Time tracking
Tool | Purpose |
| Create a time entry |
| List time entries with date/project/owner filters |
| Edit hours / date / note / service on an existing entry |
| Permanently delete a time entry |
Reports and briefings
Tool | Purpose |
| Categorised hours summary (worked/client/internal/holidays) |
| Hours summary for any team member by name |
| Projects you've logged time on recently |
| Weekly summary with hours-by-project breakdown |
Projects, people, and services
Tool | Purpose |
| List all active projects |
| Fuzzy-search projects by name and/or number |
| Fuzzy-search people by name or email |
| List services (billable activity types) on a project |
Administration
Tool | Purpose |
| Force an immediate cache refresh |
| Override the remembered default service for a project |
Key tool details
productive_get_time_report
period : str? — "this_month", "last_month", "this_week", "last_week"
after : str? — ISO date; ignored if period set
before : str? — ISO date; ignored if period set
person : str? — Name, email, id, or "me" (default)
project : str? — Scope to a specific projectReturns totals_hours: {worked, client, internal, holidays}. When PRODUCTIVE_BILLING_CUTOFF_DAY is set, "this_month" shifts based on your billing cycle.
productive_my_briefing
period : str — Default "this_week"Returns total hours, projects touched, hours-by-project breakdown, and recent entries. Designed for the Monday-morning "what am I working on?" question.
productive_get_employee_hours
person : str — Fuzzy name, email, or "me"
period : str? — Symbolic period (default: no filter)
after : str? — ISO date
before : str? — ISO dateFinds a person by fuzzy match, returns their hours for the period.
Configuration
Environment variables
Variable | Default | Purpose |
| — | API token (overrides credential store) |
| — | Organization ID (overrides credential store) |
| — | Person ID (overrides credential store) |
| unset | Day of month (1–31) when "this_month" flips to the current calendar month |
|
| Set to |
Billing cutoff day
The PRODUCTIVE_BILLING_CUTOFF_DAY controls how symbolic periods resolve for invoicing workflows:
Before cutoff day:
"this_month"= previous calendar month (you're still closing invoices)From cutoff day onward:
"this_month"= current calendar monthUnset:
"this_month"always means the current calendar month
Example: with PRODUCTIVE_BILLING_CUTOFF_DAY=10, on April 5th, "this_month" resolves to March 1–31.
Security & permissions
Credential storage
API tokens are never written to disk by this project. They live in the OS credential store (Keychain / Credential Manager / Secret Service) or in environment variables.
Productive's permission model
Each team member generates their own API token via Productive → Settings → API integrations (docs). Tokens inherit the generating user's permissions:
"API tokens inherit the same access restrictions as the user they are associated with. If a user does not have permission to access certain features or data within Productive, these limitations will also apply to their API token."
Tokens also have a read-only vs read/write scope chosen at creation time.
What this means for team deployments:
A "Member"-role user's token cannot query other members' time entries — Productive returns 403.
The real access boundary is the Productive role (Settings → People → Role), not MCP-side configuration.
Tools like
productive_get_employee_hourswill simply return empty/error for users whose Productive role doesn't grant team visibility.
For more on roles: User Permissions Overview | Productive API docs
How it works
Architecture
┌─────────────────────┐ stdio ┌──────────────────────┐ HTTPS ┌─────────────────┐
│ MCP client │ ─────────► │ productive-mcp │ ────────► │ Productive.io │
│ (Claude Code etc.) │ │ (FastMCP server) │ │ JSON:API v2 │
└─────────────────────┘ └──────────┬───────────┘ └─────────────────┘
│
▼
~/.config/productive-mcp/
├── cache.json (projects, people, services)
└── preferences.json (per-project default service)Credential lookup order
Environment variable (
PRODUCTIVE_MCP_TOKEN/_ORG_ID/_PERSON_ID)OS credential store via
keyring(Keychain / Credential Manager / Secret Service)Error with a helpful message pointing at both options
Local state
Two files under ~/.config/productive-mcp/, both 0600:
cache.json— projects, people (active only), per-project services. 1-hour TTL.preferences.json—{ "default_services": { "<project_id>": "<service_id>" } }.
Neither file ever contains credentials.
Development
uv pip install -e ".[dev]"
# unit tests (no network required)
pytest
# integration tests (hit the real Productive API — requires credentials)
pytest -m integration
# lint + type check
ruff check .
mypy srcProject layout
src/productive_mcp/
├── __main__.py Entrypoint (python -m productive_mcp)
├── server.py FastMCP tool definitions (14 tools)
├── client.py Async Productive.io API client + fuzzy matcher
├── auth.py Cross-platform credential loader (keyring + env)
├── storage.py Local cache + preferences persistence
├── periods.py Billing-cutoff-aware period resolution
└── reporting.py Time entry categorisation for reports
scripts/
└── install.sh One-shot deploy script for the global launcher
tests/
├── test_client.py Fuzzy matching + trim functions
├── test_periods.py Period resolution + billing cutoff
├── test_reporting.py Entry categorisation
└── test_formatter.py TOON output encodingTroubleshooting
"Credential store lookup failed"
The keyring backend isn't configured or accessible. Check: python -c "import keyring; print(keyring.get_keyring())". On headless Linux, use environment variables instead.
"No credential found for service=productive-mcp"
Credentials haven't been stored yet. Run the keyring.set_password(...) commands from the install section.
"No project matches 'X'"
Cache may be stale. Call productive_refresh_cache and retry.
"Ambiguous project query" Two projects scored nearly identically. Be more specific — add the project number.
"Project has multiple services; pass service_hint"
Either pass service_hint="…" (it'll be remembered), or call productive_set_default_service once upfront.
Alternatives
Several other Productive.io MCP servers exist:
berwickgeek/productive-mcp — the most feature-complete general-purpose server (projects, tasks, boards, people, workflows). Node.js. No time tracking.
adamchrabaszcz/productive-time-mcp — companion time-tracking server for the above.
druellan/Productive-Simple-MCP — read-only Python/FastMCP server using TOON output for low token usage.
laurkee/productive-mcp (Codeberg) — ticketing-focused.
Why pick this one?
Cross-platform credential store — not a
.envfile. macOS Keychain, Windows Credential Manager (TPM-backed), Linux Secret Service.Fuzzy matching for projects and people — say
"Alice"or"1099 Acme"instead of looking up IDs.Per-project default service memory — log time without specifying the service after the first call.
Billing-cutoff-aware reports —
"this_month"means what your invoicing cycle says it means.TOON output mode — 30–60% fewer tokens for long sessions.
License
MIT — see LICENSE.
Contributing
Issues and PRs welcome. Please include tests for new behaviour.
Not affiliated with Productive.io. "Productive" is a trademark of its respective owners.
Available Tools
14 toolsproductive_delete_time_entryB
Permanently delete a time entry.
Args: entry_id: Time entry ID.
Inputs: entry_id (required). Returns: object
productive_find_personA
Fuzzy-search people in the organisation by name or email.
Args: query: Partial name or email (e.g. "Alice", "alice@example.com"). limit: Max matches to return (default 5).
Inputs: query (required), limit. Returns: object
productive_find_projectA
Fuzzy-search projects by name or number.
Args: query: Partial name or number (e.g. "Acme", "1099"). limit: Max matches to return (default 5).
Inputs: query (required), limit. Returns: object
productive_get_employee_hoursA
Get a named employee's hours summary for a period.
Args: person: Person name, email, or "me" (fuzzy matched). period: Symbolic period — "this_month", "last_month", "this_week", "last_week". after: ISO date (YYYY-MM-DD). Ignored if period is set. before: ISO date (YYYY-MM-DD). Ignored if period is set.
Inputs: person (required), period, after, before. Returns: object
productive_get_time_reportA
Get a categorised hours summary (worked, client, internal, holidays).
Args: period: Symbolic period — "this_month", "last_month", "this_week", "last_week". Affected by PRODUCTIVE_BILLING_CUTOFF_DAY. after: ISO date (YYYY-MM-DD). Ignored if period is set. before: ISO date (YYYY-MM-DD). Ignored if period is set. person: Person name, email, id, or "me" (default: "me"). project: Optional project name or id to scope the report.
Inputs: period, after, before, person, +1 more. Returns: object
productive_list_projectsA
List all active Productive.io projects from local cache.
Returns id, name, number, and company for each project. Cache refreshes automatically every hour, or call productive_refresh_cache to force it.
Inputs: no named parameters. Returns: object
productive_list_servicesA
List services (billable activity types) on a given project.
Args: project: Project name (fuzzy) or numeric project id.
Inputs: project (required). Returns: object
productive_list_time_entriesA
List time entries, newest first.
Args: after: ISO date (YYYY-MM-DD) — include entries on/after this date. before: ISO date (YYYY-MM-DD) — include entries on/before this date. project: Project name or id to filter by. mine_only: If True (default), only return entries for the authenticated user.
Inputs: after, before, project, mine_only. Returns: object
productive_log_timeA
Create a time entry on a Productive.io project.
Args: project: Project name (fuzzy match, e.g. "1099 Acme") or numeric id. hours: Hours worked (float, e.g. 2.5). Converted to minutes internally. note: Optional description of the work. date: ISO date (YYYY-MM-DD). Defaults to today. service_hint: Optional service name/id if the project has multiple services. Once chosen, remembered as the project default.
Inputs: project (required), hours (required), note, date, +1 more. Returns: object
productive_my_briefingA
Get a summary of your week: projects touched, hours logged, recent entries.
Args: period: Symbolic period — defaults to "this_week". Also accepts "last_week", "this_month", "last_month".
Inputs: period. Returns: object
productive_my_projectsA
List active projects where you have logged time in the last 30 days.
Returns project id, name, number, and company for each.
Inputs: no named parameters. Returns: object
productive_refresh_cacheA
Force-refresh the projects/services/deals cache from Productive.
Call after creating new projects or services in Productive so they're visible to find_project.
Inputs: no named parameters. Returns: object
productive_set_default_serviceB
Explicitly set (or override) the remembered default service for a project.
Args: project: Project name or id. service: Service name or id. Must belong to the project.
Inputs: project (required), service (required). Returns: object
productive_update_time_entryA
Edit a time entry. Only provide fields you want to change.
Args: entry_id: Time entry ID (from productive_list_time_entries). hours: New hours value. date: New ISO date (YYYY-MM-DD). note: New note text. service_hint: New service name or id.
Inputs: entry_id (required), hours, date, note, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a clearly distinct purpose: searching people, searching projects, listing/creating/updating/deleting time entries, reporting hours, managing cache, etc. No two tools appear to do the same thing.
All tools follow a consistent verb_noun pattern with snake_case (e.g., productive_list_time_entries, productive_log_time). Even 'my_briefing' and 'my_projects' fit the pattern as personal retrieval operations.
14 tools is an appropriate number for a time-tracking MCP server, covering core operations without being overwhelming. Each tool serves a necessary function.
The tool set covers CRUD for time entries, project and person search, reporting, and cache management. Minor gaps exist (e.g., no direct 'get project details' tool, but list_projects provides adequate info).
Maintenance
Related MCP Connectors
timesheet.io MCP server - manage timers, projects, tasks and reports
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
MCP server for generating rough-draft project plans from natural-language prompts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for time tracking, project management, and AI-powered memory storage using semantic search. It enables users to log time, manage client billing, and capture shared or personal ideas through integrated tools and team collaboration features.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for time tracking and billing that allows freelancers to control timers, manage projects, and export invoices via natural language in any MCP-compatible AI assistant.6 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets LLMs interact with your Clockify workspace for time-tracking automation and reporting, enabling natural language logging of time entries, querying entries, and generating reports.MIT
- AlicenseAqualityCmaintenanceAn MCP server for the Paymo time-tracking API, enabling AI clients to read and write tasks, time entries, projects, and more via natural language.1219 npmMIT