productive-mcp

Productive.io를 위한 MCP 서버입니다. MCP 호환 클라이언트(Claude Code, Claude Desktop, Cursor 등)에서 평문 영어를 사용하여 시간을 기록하고, 프로젝트를 검토하며, 시간 항목을 관리할 수 있습니다:

"log 2.5 hours on the Acme security review project" ("Acme 보안 검토 프로젝트에 2.5시간 기록")

"show me my time entries for last week" ("지난주 시간 항목 보여줘")

"delete time entry 123456" ("시간 항목 123456 삭제")

Productive.io JSON:API v2를 기반으로 구축되었으며, 퍼지 프로젝트 매칭, 로컬 디스크 캐시, 프로젝트별 기본 서비스 메모리 기능을 제공하여 자주 사용하는 프로젝트에 시간을 기록하는 일반적인 작업을 한 문장으로 처리할 수 있습니다.

기능

• 프로젝트, 서비스, 시간 항목(목록/생성/수정/삭제)을 다루는 9가지 도구

• 퍼지 프로젝트 매칭 — "Acme", "1099 Acme", "1099" 모두 동일한 프로젝트로 인식

• 프로젝트별 기본 서비스 기억 — 매번 지정할 필요 없음

• 로컬 캐시 (프로젝트 및 서비스, 1시간 TTL, 수동 새로고침 가능)

• 자격 증명 안전성: 기본적으로 macOS 키체인에서 API 토큰을 읽음 (Linux/WSL 또는 헤드리스 사용을 위한 환경 변수 지원)

• hours 입력, hours 출력 — API는 내부적으로 분 단위를 사용하지만, 사용자는 이를 볼 필요 없음

• 기본적으로 "나"로 범위 제한 — list_time_entries는 명시적으로 제외하지 않는 한 본인의 항목만 표시

요구 사항

• Python 3.11+

• API 액세스가 활성화된 Productive.io 계정

• macOS (권장, 키체인 통합용) — Linux / WSL은 환경 변수를 통해 작동

설치

1. 복제 및 설치

git clone https://github.com/<you>/productive-mcp.git
cd productive-mcp
uv venv
uv pip install -e .

(uv를 사용하지 않는 경우 python -m venv .venv && .venv/bin/pip install -e .)

2. Productive 자격 증명 가져오기

세 가지 값이 필요합니다:

3. 자격 증명 저장

옵션 A — macOS 키체인 (macOS 권장)

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>"  -U

서버는 시작 시 security CLI를 통해 이를 조회합니다. 이 프로젝트에 의해 디스크에 기록되지 않습니다.

옵션 B — 환경 변수 (Linux / WSL / CI / 재정의)

export PRODUCTIVE_MCP_TOKEN="<token>"
export PRODUCTIVE_MCP_ORG_ID="<org_id>"
export PRODUCTIVE_MCP_PERSON_ID="<person_id>"

환경 변수는 키체인 조회보다 우선하므로, 임시로 다른 계정을 테스트하는 가장 간단한 방법이기도 합니다.

4. MCP 클라이언트에 서버 등록

Claude Code (~/.claude.json)

mcpServers 아래에 추가:

{
  "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"
    }
  }
}

설정 파일을 편집한 후 클라이언트를 다시 시작하세요.

5. (선택 사항) 번들 배포 스크립트를 사용한 전역 설치

복제 디렉토리에 묶이지 않은 공유 설치를 원하는 경우:

bash scripts/install.sh

이 작업은 새로운 venv와 run.sh 런처가 포함된 ~/.local/share/productive-mcp/를 생성합니다. MCP 클라이언트가 venv 바이너리 대신 ~/.local/share/productive-mcp/run.sh를 가리키도록 설정하세요. 스크립트를 다시 실행하면 venv가 제자리에서 업그레이드됩니다.

도구

모든 도구는 productive_ 접두사가 붙어 다른 MCP 서버와 깔끔하게 네임스페이스가 분리됩니다.

도구 참조

productive_log_time

project       : str   — Project name (fuzzy) or numeric id. e.g. "1099 Acme", "42"
hours         : float — Hours worked (e.g. 2.5). Converted to minutes internally.
note          : str?  — Description of the work
date          : str?  — ISO date (YYYY-MM-DD). Defaults to today.
service_hint  : str?  — Service name or id (only needed when the project has
                        multiple services and no remembered default)

성공 시 생성된 항목과 서비스가 선택된 방법("auto-selected only service" / "used remembered default" / "matched by name" 등)을 설명하는 service_resolution 메모를 반환합니다.

프로젝트에 서비스가 하나만 있는 경우, 자동으로 선택되어 다음 번을 위해 기본값으로 저장됩니다. 여러 개가 있는 경우, 서버는 옵션을 나열하는 실행 가능한 오류를 반환합니다.

productive_find_project

query : str — Partial name or number (e.g. "Acme", "1099 acme", "1099")
limit : int — Max matches (default 5)

가장 적합한 순서대로 정렬된 일치 항목을 반환합니다. 퍼지 스코어러는 토큰 하위 문자열 매칭, 오타를 위한 시퀀스 매처 폴백, 쿼리에 정확한 프로젝트 번호가 포함된 경우의 가중치를 결합합니다.

productive_list_time_entries

after     : str?  — Include entries on/after this ISO date
before    : str?  — Include entries on/before this ISO date
project   : str?  — Filter by project name or id
mine_only : bool  — Default True; set False to see the whole team's entries

항목은 최신순으로 반환되며, total_hours에 합계가 표시됩니다.

작동 원리

아키텍처

┌─────────────────────┐   stdio    ┌──────────────────────┐   HTTPS   ┌─────────────────┐
│  MCP client         │ ─────────► │  productive-mcp      │ ────────► │  Productive.io  │
│  (Claude Code etc.) │            │  (FastMCP server)    │           │  JSON:API v2    │
└─────────────────────┘            └──────────┬───────────┘           └─────────────────┘
                                              │
                                              ▼
                                    ~/.config/productive-mcp/
                                    ├── cache.json        (projects, services; 1h TTL)
                                    └── preferences.json  (per-project default service)

주요 설계 결정

• 서비스는 프로젝트에 속한 거래(Deal)에 범위가 지정됩니다. Productive의 데이터 모델은 이를 가시화하며, MCP는 계층 구조를 투명하게 탐색하여 "services on project X"가 바로 작동하도록 합니다.

• 시간은 유일한 사용자 대면 단위입니다. API는 시간을 분 단위로 저장하며, 이 계층은 경계에서 변환합니다.

• 기억된 기본값은 반복 작업을 줄입니다. 프로젝트에 시간을 한 번 기록하면, 이후 호출에서는 service_hint를 생략할 수 있습니다. 기본값은 preferences.json에 프로젝트별로 기억됩니다.

• 정확한 매칭보다 퍼지 매칭을 우선합니다. 대부분의 시간 기록 요청은 "project #1099"가 아니라 "that security review for Acme"와 같이 말합니다. 리졸버는 자연어에 편향되어 있습니다.

• 기본적으로 "내 항목만" 표시합니다. 거의 항상 본인을 위해 시간을 기록하므로, 팀 전체 가시성이 필요한 한 명의 사용자는 mine_only=False를 전달할 수 있습니다.

로컬 상태

~/.config/productive-mcp/ 아래에 두 개의 파일이 있으며, 모두 0600 권한으로 생성됩니다:

• cache.json — 정리된 프로젝트 목록 및 프로젝트별 서비스 조회. TTL 만료 시 또는 productive_refresh_cache를 통해 자동으로 새로고침됩니다.

• preferences.json — { "default_services": { "<project_id>": "<service_id>" } }.

두 파일 모두 자격 증명을 포함하지 않습니다.

자격 증명 조회 순서

1. 환경 변수 (PRODUCTIVE_MCP_TOKEN / _ORG_ID / _PERSON_ID)

2. macOS 키체인 (security find-generic-password -s productive-mcp -a <account>)

3. 오류 — 서버는 두 옵션을 모두 가리키는 유용한 메시지와 함께 시작을 거부합니다.

개발

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 src

디버깅을 위해 서버를 직접 실행하세요:

.venv/bin/productive-mcp
# or
python -m productive_mcp

stdio JSON-RPC로 통신하므로, 수동으로 테스트하려면 MCP 클라이언트나 mcp-inspector가 필요합니다.

프로젝트 레이아웃

src/productive_mcp/
├── __main__.py      Entrypoint (`python -m productive_mcp`)
├── server.py        FastMCP tool definitions
├── client.py        Async Productive.io API client + fuzzy matcher
├── auth.py          Keychain / env-var credential loader
└── storage.py       Local cache + preferences persistence
scripts/
└── install.sh       One-shot deploy script for the global launcher
tests/
└── test_client.py   Unit tests for trimming + fuzzy matching

문제 해결

"Keychain lookup failed" 항목이 아직 존재하지 않거나(3단계의 security add-generic-password 명령을 다시 실행) macOS가 아닌 경우입니다. 대신 환경 변수를 사용하세요.

"No project matches 'X'" 프로젝트가 최근에 생성된 경우 캐시가 오래되었을 수 있습니다. productive_refresh_cache를 호출하고 다시 시도하세요.

"Ambiguous project query" 두 프로젝트의 점수가 거의 동일합니다. 프로젝트 번호나 회사 이름을 추가하여 더 구체적으로 지정하세요.

"Project has multiple services; pass service_hint" 프로젝트에 기본값이 설정되지 않았습니다. 이 호출에서 service_hint="…"를 전달하거나(기억됨), 미리 productive_set_default_service를 호출하세요.

서버는 시작되지만 클라이언트가 "no tools"를 보고함 MCP 클라이언트가 소스 파일이 아닌 venv의 productive-mcp 바이너리(또는 run.sh 런처)를 가리키고 있는지 확인하세요. FastMCP는 핸드셰이크 시점에 도구를 알립니다. 프로세스가 mcp를 가져올 수 없으면 도구가 나타나지 않습니다.

보안 참고 사항

• API 토큰은 이 프로젝트에 의해 디스크에 기록되지 않습니다. 키체인이나 환경 변수에만 존재합니다.

• 캐시 및 기본 설정 파일은 0600 권한으로 생성되며 자격 증명을 포함하지 않습니다.

• Productive API 토큰은 사용자가 가진 것과 동일한 액세스 권한을 부여합니다. 그에 따라 취급하세요. 노출이 의심되면 Productive → 설정 → API 통합을 통해 교체하세요.

대안

다른 Productive.io MCP 서버가 존재하므로 이 서버를 채택하기 전에 확인해 볼 가치가 있습니다:

• berwickgeek/productive-mcp — 가장 기능이 완벽한 범용 서버(프로젝트, 작업, 보드, 사람, 워크플로우). Node.js. 시간 추적 없음.

• adamchrabaszcz/productive-time-mcp — 위 서버를 위한 보조 시간 추적 서버.

• druellan/Productive-Simple-MCP — 낮은 토큰 사용량을 위해 TOON 출력을 사용하는 읽기 전용 Python/FastMCP 서버.

• laurkee/productive-mcp (Codeberg) — 티켓팅 중심.

왜 이 서버를 선택해야 할까요? 이 서버는 "시간 기록 및 항목 관리" 워크플로우에 좁게 초점을 맞추고 있으며, UX는 세 가지 독단적인 선택을 기반으로 합니다:

1. 기본적으로 macOS 키체인에 자격 증명 저장, .env 파일 사용 안 함 — 토큰이 git status에 노출될 위험 없음.

2. 프로젝트 번호 가중치가 포함된 퍼지 프로젝트 매칭 — "1099 Acme" 또는 단순히 "Acme"라고 말해도 둘 다 작동.

3. 프로젝트별 기본 서비스 메모리 — 프로젝트에 첫 productive_log_time을 수행한 후, 이후 호출에서는 서비스를 지정할 필요 없음.

시간 기록보다는 작업/보드/워크플로우가 주로 필요하다면 berwickgeek/productive-mcp를 대신 사용하거나, 나란히 실행하세요(서로 다른 도구 접두사를 사용함).

라이선스

MIT — LICENSE를 참조하세요.

기여

이슈와 PR을 환영합니다. 작은 프로젝트이므로 변경 사항을 집중적으로 유지하고 client.py의 새로운 동작에 대한 테스트를 포함해 주세요.

Productive.io와 관련이 없습니다. "Productive"는 해당 소유자의 상표입니다.