clockify-mcp-server

에이전트에게 요청해서 Clockify에 프로젝트 시간을 기록하세요. 웹 UI를 클릭하는 대신 말이죠.

"이번 주 매일 아침 ACME에 4시간, 매일 오후에 Evil Corp에 4시간 추가해 줘"

→ 승인 프롬프트 한 번, 생성된 항목 10개, 총 40시간.

로컬 stdio MCP 서버입니다. 각자 자신의 API 키로 직접 실행합니다. 공유되거나 호스팅되는 것은 없습니다.

시간은 항상 Clockify 프로필 시간대 기준의 현지 시간입니다. 09:00이라고 말하면 서버는 Clockify 프로필의 settings.timeZone을 읽어 UTC로 변환합니다. UTC를 다룰 일은 없습니다. 에이전트도 마찬가지입니다.

아직 지원하지 않음: 태그, 클라이언트, 실행 중인 타이머(시작/중지), 기존 항목 편집, 보고서.

사용하기

시간을 기록하려면 필요한 전부입니다. 약 2분이면 됩니다.

1. bun 설치 (1.3.14에서 테스트) 및 의존성 설치:

curl -fsSL https://bun.sh/install | bash # install bun if needed
git clone <this-repo> && cd clockify-mcp-server
bun install

빌드 단계는 없습니다. bun이 TypeScript를 직접 실행합니다.

2. Clockify API 키 받기:

• Clockify → 아바타 → Preferences → ADVANCED 탭 → Manage API keys → GENERATE NEW

3. 에이전트에 서버 등록.

Claude Code — 방금 클론한 저장소 루트에서 그대로 복사하세요:

claude mcp add clockify -s user -e CLOCKIFY_API_KEY=<key> -- bun "$PWD/src/index.ts"

-s user는 개인 설정에 기록하므로 모든 프로젝트에서 로드됩니다. 이 디렉토리에만 국한되지 않습니다 (기본 범위인 local은 이 디렉토리에 바인딩됩니다). $PWD는 claude가 보기 전에 셸이 확장하므로 저장된 경로는 절대 경로입니다.

다른 하니스(Cursor, VS Code, Zed, Claude Desktop…) — MCP 설정에 동일한 세 가지를 넣으세요. 붙여넣을 경로를 출력합니다:

echo "$PWD/src/index.ts"

{
  "mcpServers": {
    "clockify": {
      "command": "bun",
      "args": ["<paste the absolute path here>"],
      "env": { "CLOCKIFY_API_KEY": "<key>" }
    }
  }
}

경로는 절대 경로여야 합니다: 에이전트는 이 저장소가 아닌, 작업 중인 디렉토리에서 서버를 시작합니다.

4. 확인 — 새 세션에서:

list my clockify projects
log 2 hours on <project> today from 09:00 to 11:00, description test
show my clockify entries for this week
delete that entry

두 번째 프롬프트 후 Clockify 웹 UI를 열고 항목이 09:00–11:00으로 표시되는지 확인하세요. 다른 시간으로 표시되면 Clockify 프로필 시간대가 생각과 다르다는 뜻입니다. Clockify 환경설정에서 수정하세요. 여기의 모든 것은 그 시간대를 따릅니다.

환경 변수

문제가 생기면

• CLOCKIFY_API_KEY is not set — 키가 서버 프로세스에 전달되지 않았습니다. 셸이 아니라 하니스 설정의 env에 넣으세요.

• Ambiguous project "x". Candidates: … — 의도적입니다. 서버는 id를 추측하지 않습니다. 나열된 이름 중 하나를 사용하세요.

• 모든 호출에서 404 — 워크스페이스가 리전 호스트에 있습니다. CLOCKIFY_API_BASE를 설정하세요.

• 항목이 잘못된 시간에 기록됨 — Clockify 프로필 시간대를 확인하세요(4단계 참조).

개발하기

서버를 사용하는 데는 필요 없습니다.

bun test      # unit tests, no network
bun run check # biome format + lint, applies fixes
bun run start # start the server on stdio (needs CLOCKIFY_API_KEY)

bun install은 git 훅도 설치합니다(prepare → lefthook install). 따라서 커밋 시점에 biome check --write가 스테이징된 파일에 실행되고 수정된 파일을 다시 스테이징합니다. 다른 설정은 필요 없습니다.

로컬 실행의 경우 bun은 저장소 루트의 .env를 자동으로 로드하므로, gitignore된 CLOCKIFY_API_KEY=<key>를 거기에 넣어두면 다시 입력할 필요가 없습니다. 이는 작업 디렉토리가 저장소일 때만 작동합니다. 그래서 위의 하니스 설정은 키를 명시적으로 전달하는 것입니다.

구조

src/clockify.ts      # API client, memoised user/project/task lookups, timezone conversion
src/index.ts         # McpServer + the four tools + stdio wiring
src/clockify.test.ts # the parts worth testing: DST conversion, name resolution, payload building
docs/                # Clockify API request/response samples
plans/               # what was built and what was deliberately left out

흥미로운 코드는 src/clockify.ts의 localToUtc / interval입니다. 표준 라이브러리 Intl.DateTimeFormat 왕복 변환이며 날짜 라이브러리가 없습니다. 변경 후 bun test를 실행하세요. DST 케이스가 실수를 잡아내는 경우입니다.

bun이 없는 사람에게 배포: bun build --compile --outfile clockify-mcp src/index.ts를 실행하면 하니스가 대신 가리킬 수 있는 단일 실행 바이너리가 생성됩니다.