TickTick MCP 서버 -- Claude를 위한 완벽한 TickTick 통합

License: MIT Version Python Tools Glama

28개의 도구. 전체 CRUD. 스마트 쿼리. 다중 조건 필터. 일괄 작업. GTD 지원. Dida365 호환.

Claude를 TickTick 계정에 연결하고 자연스러운 대화를 통해 전체 작업 시스템을 관리하세요. 앱을 열지 않고도 작업을 생성하고, 프로젝트 전체를 검색하고, 기한이 지난 항목을 확인하고, 항목을 일괄 생성하며 체계적으로 관리할 수 있습니다.

"기한이 지난 작업은?" --> 모든 프로젝트에서 놓친 마감일을 즉시 보여줍니다.

왜 이 서버인가요?

기능	이 서버	TickTick 공식 MCP	jacepark12
도구	28	22	~20
다중 조건 필터	예 (우선순위 + 태그 + 날짜 + 프로젝트)	예	아니요
프로젝트 간 작업 이동	예	예	아니요
일괄 완료	예 (최대 20개)	예 (최대 20개)	아니요
일괄 업데이트	예	예	아니요
완료된 작업 보기	예	예	아니요
프로젝트 간 검색	전체 텍스트 검색	예	예
하위 작업	예	아니요	아니요
GTD 포커스 뷰	예 (높은 우선순위 + 기한 + 기한 경과)	아니요	부분 지원
Dida365 지원	예 (기본 URL 구성 가능)	아니요	예
비동기 (httpx)	예	N/A	아니요 (동기 요청)
Pydantic 유효성 검사	예 (타입 지정 입력)	N/A	아니요
MCP 주석	예 (읽기 전용, 파괴적 작업 힌트)	N/A	아니요
자체 호스팅 / 오픈 소스	예	아니요 (호스팅 서비스)	예
개인정보 보호	100% 로컬, 사용자 토큰만 사용	TickTick 서버를 거침	100% 로컬

Related MCP server: mcp-server-asana

빠른 시작

사전 요구 사항

TickTick 계정
Python 3.10+
Claude Code 또는 Claude Desktop

1단계 -- 복제 및 설치

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

2단계 -- TickTick 개발자 앱 등록

developer.ticktick.com으로 이동합니다.
New App을 클릭하고 이름을 입력합니다.
OAuth Redirect URL을 http://localhost:8080/callback으로 설정합니다.
Client ID와 Client Secret을 복사합니다.

3단계 -- 인증

TICKTICK_CLIENT_ID=your_id TICKTICK_CLIENT_SECRET=your_secret .venv/bin/python3 setup_auth.py

브라우저가 열리고 앱 승인을 요청합니다. Allow를 클릭하세요. 토큰은 ~/.ticktick_mcp/tokens.json에 저장되며 자동으로 새로 고침됩니다.

4단계 -- Claude Code에 등록

claude mcp add ticktick \
  -e TICKTICK_CLIENT_ID=your_id \
  -e TICKTICK_CLIENT_SECRET=your_secret \
  -- /path/to/ticktick-mcp/.venv/bin/python3 /path/to/ticktick-mcp/server.py

Claude Desktop의 경우

claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "ticktick": {
      "type": "stdio",
      "command": "/path/to/ticktick-mcp/.venv/bin/python3",
      "args": ["/path/to/ticktick-mcp/server.py"],
      "env": {
        "TICKTICK_CLIENT_ID": "your_id",
        "TICKTICK_CLIENT_SECRET": "your_secret"
      }
    }
  }
}

5단계 -- 생산성 기술 추가 (선택 사항)

mkdir -p ~/.claude/skills/ticktick
cp skills/ticktick/SKILL.md ~/.claude/skills/ticktick/

Dida365 지원

Dida365(TickTick의 중국 버전)의 경우 다음 환경 변수를 설정하세요:

TICKTICK_BASE_URL=https://api.dida365.com/open/v1
TICKTICK_TOKEN_URL=https://dida365.com/oauth/token

사용 예시

사용자 말하기	결과
"금요일에 치과 예약하라고 알려줘"	기한이 설정된 작업 생성
"'1분기 보고서 검토'를 업무 프로젝트에 추가하고 우선순위를 높게 설정해"	업무 프로젝트에 우선순위 5인 작업 생성
"기한이 지난 작업은?"	모든 프로젝트에서 기한이 지난 작업 표시
"무엇에 집중해야 할까?"	GTD 뷰: 높은 우선순위 + 오늘 기한 + 기한 경과
"'예산'과 관련된 모든 것 검색해"	모든 프로젝트에서 전체 텍스트 검색
"높은 우선순위 작업만 보여줘"	모든 프로젝트에서 우선순위=5인 작업 필터링
"이번 주 기한인 작업은?"	향후 7일 이내 기한인 작업 표시
"작업 생성: 우유 사기, 존에게 전화하기, 보고서 제출"	3개의 작업을 일괄 생성
"'휴가 계획'이라는 프로젝트 생성해"	새 프로젝트 생성
"휴가 작업 아래에 '선크림 사기' 하위 작업 추가해"	하위 작업 생성
"치과 작업 완료했어"	작업을 완료 상태로 표시
"오래된 스프린트 프로젝트 삭제해"	프로젝트 및 모든 작업 삭제

MCP 도구 참조

프로젝트 (5개 도구)

도구	설명
`ticktick_list_projects`	ID, 이름, 색상이 포함된 모든 프로젝트 나열
`ticktick_get_project`	특정 프로젝트의 세부 정보 가져오기
`ticktick_get_project_with_tasks`	프로젝트 세부 정보 + 완료되지 않은 모든 작업을 한 번에 가져오기
`ticktick_create_project`	새 프로젝트 생성 (이름, 색상, 보기 모드)
`ticktick_update_project`	프로젝트 이름, 색상 또는 보기 모드 업데이트
`ticktick_delete_project`	프로젝트 영구 삭제

작업 -- 기본 CRUD (7개 도구)

도구	설명
`ticktick_list_tasks`	특정 프로젝트의 모든 작업 나열
`ticktick_create_task`	작업 생성 (제목, 기한, 우선순위, 프로젝트, 태그)
`ticktick_get_task`	특정 작업의 전체 세부 정보 가져오기
`ticktick_update_task`	제목, 내용, 날짜 또는 우선순위 업데이트
`ticktick_complete_task`	작업을 완료로 표시
`ticktick_delete_task`	작업 영구 삭제
`ticktick_create_subtask`	상위 작업 아래에 하위 작업 생성

작업 -- 스마트 쿼리 (7개 도구)

도구	설명
`ticktick_get_all_tasks`	모든 활성 프로젝트의 모든 작업 가져오기
`ticktick_search_tasks`	제목, 내용, 하위 작업에 대한 전체 텍스트 검색
`ticktick_get_tasks_by_priority`	우선순위별 필터링 (없음/낮음/중간/높음)
`ticktick_get_tasks_due_today`	모든 프로젝트에서 오늘 기한인 작업
`ticktick_get_overdue_tasks`	모든 프로젝트에서 기한이 지난 모든 작업
`ticktick_get_tasks_due_this_week`	향후 7일 이내 기한인 작업
`ticktick_get_tasks_due_in_days`	정확히 N일 후 기한인 작업

작업 -- 일괄 처리 및 생산성 (5개 도구)

도구	설명
`ticktick_batch_create_tasks`	여러 작업을 한 번에 생성
`ticktick_batch_update_tasks`	여러 작업을 한 번에 업데이트
`ticktick_complete_tasks_bulk`	최대 20개의 작업을 한 번에 완료 표시
`ticktick_move_task`	작업을 다른 프로젝트로 이동
`ticktick_get_focus_tasks`	GTD 포커스 뷰: 높은 우선순위 + 오늘 기한 + 기한 경과

작업 -- 고급 필터 (2개 도구)

도구	설명
`ticktick_filter_tasks`	다중 조건 필터: 우선순위 + 태그 + 날짜 범위 + 프로젝트 + 상태
`ticktick_get_completed_tasks`	프로젝트에서 완료된 작업 보기

사용자 (1개 도구)

도구	설명
`ticktick_get_user_preferences`	사용자 설정 가져오기 (시간대, 주 시작일 등)

아키텍처

server.py              # 20 MCP tools, async httpx, Pydantic validation
setup_auth.py          # One-time OAuth 2.0 setup (browser-based)
~/.ticktick_mcp/       # Token storage (auto-refreshed)
skills/ticktick/       # Claude skill for natural task language

설계 선택:

모든 곳에 비동기 적용 -- 차단 없는 API 호출을 위한 httpx.AsyncClient 사용
Pydantic 입력 모델 -- 명확한 오류 메시지와 함께 타입 안전성이 보장된 입력
MCP 주석 -- 더 안전한 도구 사용을 위한 readOnlyHint, destructiveHint 사용
자동 토큰 새로 고침 -- 60초 버퍼를 사용하여 토큰이 투명하게 새로 고침됨

문제 해결

"Given client ID does not match" -- developer.ticktick.com에서 Client ID를 다시 확인하세요.

Port 8080 already in use -- lsof -ti:8080 | xargs kill -9를 실행한 후 다시 시도하세요.

Tokens expired -- setup_auth.py를 다시 실행하여 새 토큰을 받으세요.

Claude doesn't see tools -- claude mcp list를 실행하여 등록 여부를 확인하세요.

기여

기여를 환영합니다! 변경하고 싶은 내용이 있으면 먼저 이슈를 열어 논의해 주세요.

git clone https://github.com/Salen-Project/ticktick-mcp
cd ticktick-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
# Make your changes to server.py
# Test: python3 -c "from server import mcp; print(len(mcp._tool_manager._tools), 'tools')"

링크

라이선스

MIT (c) Salen-Project

ticktick-mcp