ticktick-mcp

TickTick 작업 관리를 위한 MCP 서버입니다. TickTick v2 API를 통해 작업을 생성, 업데이트, 완료, 이동, 필터링할 수 있으며, 필드 보존 업데이트, 요일 날짜 검증, 쓰기 후 읽기 검증, 멱등적 완료 추적을 지원합니다.

Claude Code 및 기타 MCP 클라이언트를 위해 설계되었습니다.

비공식 프로젝트입니다. TickTick Ltd.와 관련이 없습니다. ticktick-py(MIT)를 기반으로 구축되었습니다.

기능

• 전체 작업 수명 주기 - 생성, 업데이트, 완료, 이동, 하위 작업, 삭제

• 필드 보존 업데이트 - ticktick_update_task는 작업을 다시 가져와서 사용자가 설정한 필드만 덮어쓰므로 API가 생략한 필드를 절대 지우지 않습니다

• 요일 검증 - 날짜를 설정하는 모든 호출은 요일을 확인해야 하며, 서버에 도달하기 전에 하루 차이 나는 날짜 오류를 잡아냅니다

• 쓰기 후 읽기 검증 - 생성/업데이트 시 작업을 다시 읽고 서버 응답이 일치하지 않으면 _verification_warnings를 표시합니다

• 간결한 목록 - 목록 도구는 기본적으로 축소된 보기를 반환하므로 대규모 프로젝트도 MCP 결과 크기 상한을 초과하지 않습니다(아래 참조)

• 최신 읽기 - 읽기 도구는 요청 시 서버 상태를 다시 동기화하므로 다른 기기의 TickTick 앱에서 수정한 내용이 재시작 없이 반영됩니다

• 완료 추적 - 완료된 작업을 처리됨으로 표시하여 에이전트가 각 작업을 정확히 한 번만 검토하도록 합니다

Related MCP server: ticktick-mcp-server

요구 사항

• Python 3.13+

• uv (권장 - 아래 설치 참고 사항 참조)

• TickTick 계정

• OAuth 자격 증명을 위한 등록된 TickTick 앱(무료 - developer.ticktick.com)

설치

git clone https://github.com/partymola/ticktick-mcp
cd ticktick-mcp
uv sync

이렇게 하면 .venv가 생성되고 uv.lock에서 설치되어 콘솔 스크립트가 .venv/bin/ticktick-mcp(Windows에서는 .venv\Scripts\ticktick-mcp)로 제공됩니다. 아래의 모든 명령은 POSIX 방식으로 표기합니다.

pip install .도 작동합니다. 이 서버가 필요로 하는 ticktick-py 포크는 dependencies 안에 직접 git 참조로 고정되어 있으며 pip와 uv 모두 이를 존중합니다. uv sync는 버전을 다시 해석하지 않고 uv.lock의 정확한 버전을 설치하므로 권장됩니다.

자격 증명

TickTick 로그인에는 두 가지가 필요합니다: OAuth 앱(클라이언트 ID + 시크릿)과 본인의 계정 로그인입니다.

1. developer.ticktick.com에서 앱을 등록하세요. Redirect URI를 http://localhost:8080/redirect로 설정하세요. Client ID와 Client Secret을 기록해 두세요.

2. 템플릿을 서버가 읽는 디렉터리로 복사하고 내용을 채우세요:

   mkdir -p ~/.config/ticktick-mcp && cp .env.example ~/.config/ticktick-mcp/.env

   TICKTICK_CLIENT_ID=your_client_id
   TICKTICK_CLIENT_SECRET=your_client_secret
   TICKTICK_REDIRECT_URI=http://localhost:8080/redirect
   TICKTICK_USERNAME=your_ticktick_email
   TICKTICK_PASSWORD=your_ticktick_password

3. 이 파일에는 계정 비밀번호가 평문으로 저장되며 서버가 이 파일을 생성하지 않으므로 직접 권한을 강화하세요. POSIX에서:

   chmod 700 ~/.config/ticktick-mcp
   chmod 600 ~/.config/ticktick-mcp/.env

   이것은 POSIX 모드 비트이며 Windows에서는 아무 효과가 없습니다. Windows에서의 접근은 파일이 상위 디렉터리에서 상속하는 ACL을 따릅니다. 두 명령에 해당하는 Windows 명령은 여기에 문서화되어 있지 않습니다.

   옆에 있는 두 토큰 파일은 소유자 전용으로 생성되며 서버가 생성하는 구성 디렉터리도 마찬가지입니다. 단, 이미 존재하는 디렉터리는 그대로 둡니다. 이것들도 POSIX 모드이며 Windows에서도 설정되지만, Windows에서는 누가 무엇을 읽을 수 있는지 제한하지 않습니다.

서버를 등록하기 전에 터미널에서 한 번 인증하세요:

.venv/bin/ticktick-mcp auth

브라우저가 열리고 도착한 URL을 다시 붙여넣으라고 요청한 후 종료됩니다. 토큰은 .env 옆에 .token-oauth로 캐시되며 이후 모든 시작에서 재사용됩니다. TickTick은 리프레시 토큰을 발급하지 않으므로 토큰이 만료되면 이 과정이 반복됩니다. 같은 명령을 다시 실행하세요.

이 단계를 MCP 서버 내부에서 실행하지 마세요. 프롬프트는 표준 입력에서 읽는데, stdio 서버의 표준 입력은 JSON-RPC 채널이므로 인증되지 않은 첫 도구 호출이 호스트에서 브라우저를 열고 차단됩니다. 컨테이너에서는 전혀 완료할 수 없습니다. 호스트에서 auth를 실행하고 구성 디렉터리를 마운트하세요.

사용자 이름/비밀번호 부분은 별도 단계가 필요 없습니다. 서버는 첫 도구 호출 시 지연 로그인하고 해당 세션 토큰을 .token-v2로 캐시하므로 매 시작마다 자격 증명을 다시 제출하지 않습니다.

서버는 다음 순서로 .env를 찾습니다: --dotenv-dir <path> 인자, 그다음 TICKTICK_MCP_DOTENV_DIR 환경 변수, 그다음 ~/.config/ticktick-mcp/. .env가 없으면 TICKTICK_* 환경 변수를 직접 사용하는데, 이는 컨테이너/CI 사용에 편리합니다.

개인정보 보호 및 비공식 API

귀하의 TickTick 자격 증명은 로컬 .env(또는 환경)에만 존재하며 TickTick 자체 서버에만 전송됩니다. 개발자나 제3자에게는 절대 전송되지 않습니다. 서버는 귀하의 계정만 읽고 씁니다.

이 서버는 공식 Open API 대신 TickTick의 비공식 v2 API(ticktick-py 경유)를 사용합니다. 이는 의도적인 선택입니다. 공식 API에는 완료된 작업 목록 엔드포인트, 태그, 프로젝트 간 작업 목록이 없으며, 이 서버는 이 모두에 의존합니다. 전체 근거, 위험 트레이드오프, 재고하게 만드는 트리거는 docs/why-not-the-official-api.md를 참조하세요.

Claude Code에 등록

claude mcp add -s user ticktick -- /path/to/ticktick-mcp/.venv/bin/ticktick-mcp --dotenv-dir /path/to/config

.env가 ~/.config/ticktick-mcp/에 있거나 환경을 통해 TICKTICK_* 변수를 제공하는 경우 --dotenv-dir는 선택 사항입니다.

그런 다음 Claude에게 다음과 같이 요청하세요:

• "이번 주 TickTick 목록에 뭐가 있지?"

• "금요일 오전 9시에 치과에 전화하는 작업을 추가해 줘."

• "장보기 작업을 완료로 표시해 줘."

• "예산 작업을 Finance 프로젝트로 옮겨 줘."

Docker

이미지는 ghcr.io/partymola/ticktick-mcp에 게시됩니다. 태그에는 v 접두사(:vX.Y.Z)가 붙으며 :latest는 가장 최근 릴리스를 따릅니다.

브라우저가 있는 머신에서 먼저 인증한 후 해당 디렉터리를 마운트하세요. 이것이 유일한 방법이며 docker run -it에서도 유효합니다. 기본 라이브러리가 브라우저를 직접 열고 URL을 절대 출력하지 않으므로 브라우저가 없는 컨테이너에서 복사해 낼 것이 없습니다. 그런 다음 표준 입력에서 해당 URL을 기다리는데, stdio 서버의 표준 입력은 JSON-RPC 채널입니다. 따라서 캐시된 토큰이 없는 디렉터리로 시작된 컨테이너도 깔끔하게 실패하지 않습니다. 도착하지 않는 입력을 기다리며 클라이언트의 요청을 소비합니다.

인증하려면 소스 설치(Install)와 Credentials의 자격 증명이 필요합니다. 실행할 수 있는 게시된 패키지가 없습니다. pip install ticktick-mcp를 실행하지 마세요: PyPI의 해당 이름은 거의 동일한 설명을 가진 무관한 프로젝트에 속합니다.

.venv/bin/ticktick-mcp auth       # once, on the host, in a terminal

claude mcp add -s user ticktick -- \
  docker run --rm -i --user $(id -u):$(id -g) \
  -v ~/.config/ticktick-mcp:/data \
  ghcr.io/partymola/ticktick-mcp:latest

-i는 필수입니다. 서버는 stdin과 stdout을 통해 JSON-RPC로 통신합니다.

--user는 컨테이너가 기본적으로 root로 실행되기 때문에 필요합니다. 컨테이너가 마운트된 디렉터리에 쓰는 모든 것은 root 소유가 되며, 이후 호스트 측 ticktick-mcp는 세션 토큰 캐시를 업데이트할 수 없게 되어 매 시작 시 제한된 로그인으로 대체됩니다. 호스트에서 다시 실행하게 될 것입니다. OAuth 토큰에는 리프레시가 없으므로 만료 시 auth가 반복됩니다.

이미 인증된 디렉터리를 마운트하고, 절대 빈 볼륨을 마운트하지 마세요. /data에는 .env, 캐시된 OAuth 토큰, v2 세션 토큰, 완료 추적 데이터베이스가 들어 있습니다. 새 볼륨에는 이 중 아무것도 없으며, 비밀번호 로그인 대체는 15-30분 잠금으로 제한됩니다.

디스크에 .env를 전혀 두고 싶지 않다면 자격 증명을 환경 변수로 전달하세요. 마운트는 여전히 필요합니다. 마운트에는 .env뿐만 아니라 토큰 캐시도 들어 있기 때문입니다:

docker run --rm -i --user $(id -u):$(id -g) \
  -v ~/.config/ticktick-mcp:/data \
  -e TICKTICK_CLIENT_ID -e TICKTICK_CLIENT_SECRET \
  -e TICKTICK_USERNAME -e TICKTICK_PASSWORD \
  ghcr.io/partymola/ticktick-mcp:latest

값 없이 각 변수의 이름만 지정하면 셸에서 그대로 전달되므로 명령이나 셸 기록에 비밀이 나타나지 않습니다. 이 변수들은 마운트된 .env를 **재정의(override)**합니다. 파일은 override 없이 로드되므로 이미 환경에 있는 값이 우선합니다. auth도 읽을 .env가 없으므로 인증 시에도 호스트에서 해당 변수를 내보내야 합니다.

CLI

ticktick-mcp                       Start the MCP server (stdio transport)
ticktick-mcp --dotenv-dir PATH     Directory holding the .env file
ticktick-mcp --version             Print the installed package version

auth는 유일한 다른 하위 명령이며, 브라우저 단계가 서버 내부가 아닌 터미널에서 이루어지도록 존재합니다. 모든 작업 조작은 아래의 MCP 도구를 통해 이루어집니다.

MCP 도구

프로젝트: 이름 또는 ID

프로젝트 ID를 받는 모든 도구는 프로젝트의 이름도 받습니다 - ticktick_create_task, ticktick_get_tasks_from_project, ticktick_update_task, ticktick_move_task, ticktick_delete_tasks, ticktick_filter_tasks 및 두 완료 추적 도구:

ticktick_create_task(title="Renew insurance", project_id="Home Admin")

이름은 대소문자를 구분하지 않고 주변 공백을 무시하며, "Inbox"는 받은 편지함으로 해석됩니다. ID는 변경 없이 계속 작동하며 항상 우선하므로 현재 작동하는 것은 변경되지 않습니다.

새로 추가된 유일한 오류는 모호성입니다. 두 프로젝트가 같은 이름을 공유하면 호출이 실패하고 하나를 선택하는 대신 두 ID를 모두 명시합니다. 추측으로 작업을 찾지 않을 곳에 넣을 수 있기 때문입니다. 서버가 해석할 수 없는 다른 모든 것은 이전과 정확히 동일하게 API에 그대로 전달됩니다.

완료 추적 도구 두 개는 예외다. 확인할 수 없는 프로젝트 참조를 그대로 전달하지 않고 거부하는데, 그 값이 로컬 데이터베이스가 기록되는 키이기 때문이다. 확인할 수 없는 참조는 나중에 ID로 조회해도 찾을 수 없는 행을 쓰게 된다. 프로젝트 목록을 새로 고쳐 확인할 수 없으면 프로젝트가 존재하지 않는다고 주장하는 대신 그렇게 알린다(outcome: "project_list_unverifiable").

작업 나열: 기본값은 간결(compact)

목록을 반환하는 도구(ticktick_get_tasks_from_project 및 ticktick_filter_tasks)는 기본적으로 detail="compact"를 사용한다. 간결 출력은 탐색에 필요한 필드(id, projectId, title, dueDate, startDate, priority, status, isAllDay, timeZone, tags)와 contentPreview(content의 처음 약 200자)를 유지하고, 용량이 큰 content/desc/체크리스트 items 블롭과 부피 큰 동기화 메타데이터는 제외한다. 이렇게 하면 큰 프로젝트도 MCP 결과 크기 상한 안에 들어와 클라이언트가 결과를 디스크로 넘기지 않아도 된다. 키워드 검색은 여전히 title과 contentPreview를 대상으로 동작한다.

• 전체 객체가 필요한가? detail="full"을 전달하라.

• 한 작업의 전체 내용이 필요한가? ticktick_get_by_id를 사용하라.

• 작업 편집: 먼저 ticktick_get_by_id로 전체 객체를 가져온 다음, 모든 필드를 ticktick_update_task로 다시 보내라. TickTick API는 업데이트에서 누락된 필드를 지워버리므로, 간결형 출력은 절대 업데이트에 사용해선 안 된다.

간결형 결과가 여전히 크기 예산을 초과하면, 마감이 가장 가까운 작업부터 반환되고 마지막 _truncation_note 요소가 얼마나 많은 작업이 생략되었는지 보고한다. 조용히 버려지는 것은 없다. 나머지 작업은 더 좁은 ticktick_filter_tasks 쿼리, detail="full", 또는 ticktick_get_by_id로 접근하라.

최신성: 읽기는 항상 최신 상태 유지

서버가 실행되는 동안 TickTick 계정은 다른 기기의 앱에서 편집될 수 있다. 읽기가 오래된 상태가 되지 않도록, 읽기 도구는 요청 시 서버 상태를 다시 동기화하며, 창당 최대 한 번으로 제한된다(기본 15초, TICKTICK_MCP_SYNC_TTL_SECONDS로 재정의 가능). 다른 곳에서 변경된 사항은 그 창 안에 표시된다. ticktick_sync를 호출하면 즉시 새로고침하고 현재 작업/프로젝트 수를 얻을 수 있다. 동기화가 실패하면 오류를 내는 대신 마지막으로 알려진 상태를 제공한다 - 단, ticktick_get_all은 예외로, 매 호출마다 새로고침하고 실패를 대신 보고한다. 전체 덤프는 조용히 오래된 답변을 제공하기에 적절한 곳이 아니기 때문이다.

구성

작업 수정으로부터 보호

어떤 작업은 에이전트가 무엇을 요청받든 절대 변경해서는 안 된다. 해당 ID를 TICKTICK_MCP_PROTECTED_TASK_IDS에 나열하라:

TICKTICK_MCP_PROTECTED_TASK_IDS="60ca9dbc8f08516d9dd56324,60ca9dbc8f08516d9dd56325"

ticktick_update_task, ticktick_complete_task, ticktick_delete_tasks, ticktick_move_task 및 ticktick_make_subtask는 보호된 작업을 명명하는 모든 호출을 거부하고 outcome: "protected_task"를 반환한다. 작업을 읽거나 쓰는 요청은 전송되지 않는다. 보호된 ID가 포함된 일괄 삭제는 부분 적용 대신 전체가 거부된다. 부분 삭제는 되돌릴 수 없기 때문이다.

TickTick은 삭제와 이동을 하위 작업으로 전파하므로, delete, move 및 make_subtask는 보호된 작업이 명명한 작업의 상위 또는 하위 작업인 경우에도 거부한다. 이 검사는 먼저 로컬 상태를 새로고침하므로, 보호가 구성된 동안 삭제, 이동 또는 재부모화마다 요청 하나가 추가된다 - 그리고 새로고침이 실패하면 outcome: "protection_unverifiable"을 반환한다. 갱신할 수 없는 스냅샷에서 보호된 하위 작업을 배제할 수 없기 때문이다. 변수가 설정되지 않으면 추가 작업을 전혀 하지 않는다. ID는 주변 공백, 따옴표, 대소문자를 무시하고 일치한다. 보호된 작업 읽기는 항상 동작한다.

자격 증명(TICKTICK_CLIENT_ID, TICKTICK_CLIENT_SECRET, TICKTICK_REDIRECT_URI, TICKTICK_USERNAME, TICKTICK_PASSWORD)은 .env 파일에서 읽거나, 없으면 환경에서 직접 읽는다.

데이터 안전

사전 커밋 훅(scripts/check-no-data.sh)은 데이터베이스, 자격 증명, 대용량 파일의 우발적 커밋을 차단한다 - *.db 및 백업 변형, config/ 아래의 모든 것(.gitkeep 및 *.example* 제외), 100KB 초과 파일(uv.lock 제외). 클론 후 설치하라:

ln -sf ../../scripts/check-no-data.sh .git/hooks/pre-commit

기여

개발 설정, 테스트 워크플로, 사전 커밋 훅은 CONTRIBUTING.md를 참조하라. 변경 사항은 CHANGELOG.md에 추적된다.

라이선스

GPL-3.0-or-later