productive-mcp
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