TickTick MCP 서버

이 MCP 서버로 TickTick 워크플로를 강화하세요. ticktick-py 라이브러리를 기반으로 구축된 이 서버는 크게 향상된 필터링 기능을 제공하여 AI 어시스턴트와 MCP 호환 애플리케이션(예: Claude Desktop, VS Code Agent Mode, mcp-use )이 더욱 정밀하고 강력하게 작업과 상호 작용할 수 있도록 지원합니다.

✨ 특징

이 서버는 MCP 도구를 통해 TickTick 기능에 대한 포괄적인 액세스를 제공하며, 다음과 같이 분류됩니다.

작업 관리: 작업을 만들고, 업데이트하고(TickTick의 날짜 형식으로 변환 포함), 삭제하고, 완료하고, 이동합니다.
하위 작업 관리: 기존 작업을 연결하여 하위 작업을 만듭니다.
작업 검색:
- 완료되지 않은 모든 작업을 가져옵니다.
- ID 또는 특정 필드별로 작업을 가져옵니다.
- 특정 날짜 범위 내에서 완료된 작업을 가져옵니다.
- 특정 프로젝트에서 작업을 가져옵니다.
- 다양한 기준(우선순위, 프로젝트, 태그 등)을 기준으로 작업을 필터링합니다.
프로젝트/태그 관리: 모든 프로젝트, 태그, 프로젝트 폴더를 검색합니다.
도우미 도구: 날짜/시간 문자열을 필요한 TickTick 형식으로 변환합니다.

자세한 사양은 src/ticktick_mcp/tools/ 디렉토리 내의 도구 정의를 참조하세요.

🚀 시작하기

이 서버는 TickTick API와 상호 작용하기 위해 비공식적인 ticktick-py 라이브러리를 활용합니다.

필수 조건

파이썬 >= 3.10
TickTick 및 API 자격 증명에 대한 액세스(아래 참조).

설정

TickTick 애플리케이션 등록: 서버를 사용하기 전에 TickTick에 애플리케이션을 등록하여 API 자격 증명을 받아야 합니다. ticktick-py 문서를 기반으로 다음 단계를 따르세요.
- TickTick OpenAPI 문서 로 가서 TickTick 계정으로 로그인하세요.
- 오른쪽 상단 모서리에 있는 Manage Apps 클릭하세요.
- +App Name 버튼을 클릭하여 새 앱을 등록하세요. 애플리케이션 이름을 입력하세요(예: "MCP 서버").
- 앱 생성 후 앱 세부 정보를 편집하세요. 생성된 Client ID 와 Client Secret 기록해 두세요.
- OAuth Redirect URL 에는 애플리케이션 승인 후 리디렉션될 URL을 입력하세요. 실제 URL일 필요는 없습니다.
  - 로컬 개발에는 http://localhost:8080/redirect 또는 http://127.0.0.1:8080/ 이 일반적인 선택입니다.
  - 이 정확한 URL이 환경 변수에 저장되었는지 확인하세요.
환경 변수: 서버에는 방금 얻은 TickTick API 자격 증명과 TickTick 로그인 정보가 필요합니다. 기본적으로 ~/.config/ticktick-mcp/.env 에 있는 .env 파일을 찾습니다.
- ~/.config/ticktick-mcp/ 디렉토리가 없으면 서버가 직접 생성 할 수도 있지만 , 수동으로 생성하는 것이 더 안전합니다.
- 해당 디렉토리 내에 .env 파일을 수동으로 만들어야 합니다 .
- 또는 Python을 통해 서버를 직접 실행할 때만 --dotenv-dir 명령줄 인수를 사용하여 다른 디렉터리를 지정할 수 있습니다(아래 "서버 실행" 참조). .env 파일에는 다음이 포함되어야 합니다.

지엑스피1

인증(첫 번째 실행): 첫 번째 실행(직접 또는 MCP 클라이언트를 통해) 시, 기본 ticktick-py 라이브러리가 OAuth2 인증 흐름을 시작합니다.
- 웹 브라우저 창이 자동으로 열리거나 URL이 콘솔/로그 출력에 인쇄됩니다.
- 이 URL을 방문하고, 필요한 경우 TickTick에 로그인하고, 애플리케이션을 승인(읽기 및 쓰기 권한 부여)해야 합니다.
- 승인 후, 귀하가 지정한 TICKTICK_REDIRECT_URI 로 리디렉션됩니다.
  - 콘솔에서는 이 전체 리디렉션 URL ( code= 매개변수 포함)을 터미널에 다시 붙여넣으라는 메시지가 표시됩니다.
- 성공적으로 검증되면 .env 파일과 같은 디렉토리에 .token-oauth 파일이 생성됩니다.
- 이 파일은 인증 토큰을 캐시하므로 일반적으로 약 6개월에 한 번 또는 토큰이 유효하지 않게 될 때만 이 수동 인증 단계를 수행하면 됩니다.

서버 실행

서버는 두 가지 주요 방법으로 실행할 수 있습니다.

1. MCP 클라이언트를 통해(AI Assistant 통합에 권장):

MCP 클라이언트(예: Claude Desktop, VS Code Agent Mode 등)를 구성하여 서버를 사용하세요. 구성 예시:

{
 "mcpServers": {
 "ticktick": {
  "command": "uvx",
  "args": [
  "--from",
  "git+https://github.com/jen6/ticktick-mcp.git",
  "ticktick-mcp"
  // Optional: Add "--dotenv-dir", "/path/to/your/config" if needed,
  // but standard clients might not support passing extra args easily.
  ]
 }
 }
}

🔧 도구

이 서버는 TickTick 작업 관리 서비스와 상호 작용하기 위한 다음과 같은 도구를 제공합니다.

작업 관리

ticktick_create_task
- TickTick에서 새 작업을 만듭니다.
- 입력:
  - title (문자열): 작업의 제목입니다. 필수입니다.
  - projectId (문자열, 선택 사항): 작업을 추가할 프로젝트의 ID입니다.
  - content (문자열, 선택 사항): 작업에 대한 추가 세부 정보 또는 메모입니다.
  - desc (문자열, 선택 사항): 작업에 대한 설명입니다.
  - allDay (부울, 선택 사항): 작업이 하루 종일 지속되는 경우 True로 설정합니다.
  - startDate (문자열, 선택 사항): ISO 8601 형식의 시작 날짜/시간입니다.
  - dueDate (문자열, 선택 사항): ISO 8601 형식의 마감일/시간입니다.
  - timeZone (문자열, 선택 사항): IANA 시간대 이름(예: 'Asia/Seoul').
  - reminders (문자열 배열, 선택 사항): RFC 5545 형식의 알림 트리거 목록입니다.
  - repeat (문자열, 선택 사항): RFC 5545 형식의 반복 규칙입니다.
  - priority (정수, 선택 사항): 작업 우선순위(0=없음, 1=낮음, 3=보통, 5=높음).
  - sortOrder (정수, 선택 사항): 사용자 지정 정렬 순서 값.
  - items (객체 배열, 선택 사항): 하위 작업 사전 목록입니다.
ticktick_update_task
- 기존 작업을 업데이트합니다
- 입력:
  - task_object (객체): 작업 id 포함하여 업데이트할 작업 속성이 있는 사전입니다.
ticktick_delete_tasks
- 하나 이상의 작업을 삭제합니다
- 입력:
  - task_ids (문자열 또는 문자열 배열): 삭제할 단일 작업 ID 또는 작업 ID 목록입니다.
ticktick_complete_task
- 작업을 완료로 표시합니다
- 입력:
  - task_id (문자열): 완료로 표시할 작업의 ID입니다.
ticktick_move_task
- 작업을 다른 프로젝트로 이동합니다.
- 입력:
  - task_id (문자열): 이동할 작업의 ID입니다.
  - new_project_id (문자열): 대상 프로젝트의 ID입니다.
ticktick_make_subtask
- 한 작업을 다른 작업의 하위 작업으로 만듭니다.
- 입력:
  - parent_task_id (문자열): 부모가 될 작업의 ID입니다.
  - child_task_id (문자열): 하위 작업이 될 작업의 ID입니다.

작업 검색

ticktick_get_by_id
- ID로 특정 객체(작업, 프로젝트 등)를 검색합니다.
- 입력:
  - obj_id (문자열): 검색할 객체의 고유 ID입니다.
ticktick_get_all
- 지정된 유형의 모든 객체를 검색합니다
- 입력:
  - search (문자열): 검색할 객체의 유형(예: '작업', '프로젝트', '태그').
ticktick_get_tasks_from_project
- 특정 프로젝트에서 완료되지 않은 모든 작업을 검색합니다.
- 입력:
  - project_id (문자열): 프로젝트의 ID입니다.
ticktick_filter_tasks

다양한 기준에 따라 작업을 필터링합니다.
입력:
- filter_criteria (객체): 다음과 같은 필터링 매개변수가 포함된 사전:
  - status (문자열): 작업 상태('미완료' 또는 '완료').
  - project_id (문자열, 선택 사항): 작업을 필터링할 프로젝트 ID입니다.
  - tag_label (문자열, 선택 사항): 작업을 필터링할 태그 이름입니다.
  - priority (정수, 선택 사항): 우선순위 수준.
  - due_start_date (문자열, 선택 사항): 출산 예정일 필터의 ISO 형식 시작 날짜입니다.
  - due_end_date (문자열, 선택 사항): 기한 필터에 대한 ISO 형식의 종료 날짜입니다.
  - completion_start_date (문자열, 선택 사항): 완료 날짜 필터의 시작 날짜입니다.
  - completion_end_date (문자열, 선택 사항): 완료 날짜 필터의 종료 날짜입니다.
  - sort_by_priority (부울, 선택 사항): 우선순위에 따라 결과를 정렬합니다.
  - tz (문자열, 선택 사항): 날짜 해석을 위한 시간대입니다.

도우미 도구

ticktick_convert_datetime_to_ticktick_format

ISO 8601 날짜/시간 문자열을 TickTick API 형식으로 변환합니다.
입력:
- datetime_iso_string (문자열): ISO 8601 형식의 날짜/시간 문자열입니다.
- tz (문자열): 날짜/시간을 해석하기 위한 IANA 시간대 이름입니다.

🤖 샘플 에이전트 프롬프트

## Persona: Daily Stand-up Agent

- **Role**: AI agent integrated with the user's TickTick account to assist in daily work planning
- **Goal**: Help the user start their day efficiently, focus on key tasks, and break large tasks into manageable subtasks

---

## Core Features & Workflow

1. **Fetch Current Time** 
 - Retrieve current time using `time mcp`.

2. **Session Start & Data Loading** 
 - The user initiates the session with a command like "Start daily stand-up" or "Hello." 
 - Call TickTick MCP API to fetch all tasks due **today**. 
 - Optionally notify the user that data is loading (e.g., "Fetching today's and overdue tasks from TickTick…").

3. **Daily Briefing**
 Good morning! Today's date is {YYYY-MM-DD}. Here's your daily stand-up from TickTick:

 **Tasks Due Today:**
 - Task Name 1
 - Task Name 2
 …

 **Overdue Tasks:**
 - Task Name 3
 - Task Name 4
 …

4. **Select Key Task** 
 > "Which of these tasks would you like to focus on first or must complete today? 
 > Or is there another important task you'd like to add?"

5. **Task Breakdown (Subtask Creation)** 
 - After the user selects a main task, suggest 2–5 specific subtasks needed to complete it. 
 - Example (if "Write project report" is selected):
  1. Draft outline & table of contents (10 min) 
  2. Gather & analyze data (30 min) 
  3. Write section drafts (1 h) 
  4. Review & revise draft (30 min) 
  5. Final submission (10 min)

6. **Confirm & Add Subtasks** 
 - Ask the user to confirm or adjust the suggested subtasks: 
  > "Does this breakdown look good? Any changes?" 
 - Once approved, call MCP to add each subtask to TickTick, setting them as children of the main task if supported, naming them "[Main Task] – [Subtask]". 
 mcp.ticktick.addTask({
  name: "[Main Task] – [Subtask]",
  parentId: "..."
 });

7. **Session Close** 
 > "All subtasks have been added to TickTick. Have a productive day! Anything else I can help with?"

---

## Additional Guidelines

- **Tone & Manner**: Friendly, proactive, and organized. 
- **MCP Interface Examples**: 
 // Fetch today's due tasks
 mcp.ticktick.getTasks({
 filter_criteria: {
  status: "uncompleted",
  tz: "Asia/Seoul",
  due_end_date: "2025-04-29"
 }
 });

 // Add a subtask
 mcp.ticktick.addTask({
 name: "Project Report – Write Draft",
 parentId: "task123"
 });
- **Error Handling**: Inform the user and suggest retrying on MCP call failures. 
- **Clarity**: Present task lists and subtask suggestions clearly. 
- **Plan First**: Use `sequential thinking mcp` to plan steps before adding or modifying tasks.

🤝 기여하기

기여를 환영합니다! 이슈를 개설하거나 풀 리퀘스트를 제출해 주세요.

📜 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

🔗 또한 참조하세요

모델 컨텍스트 프로토콜 서버 : 다양한 도구와 플랫폼을 위한 MCP 서버의 참조 구현을 위한 중앙 저장소입니다.
modelcontextprotocol.io : 모델 컨텍스트 프로토콜에 대한 공식 문서입니다.
pietrozullo/mcp-use : MCP 서버와 상호 작용하는 클라이언트/에이전트를 구축하기 위한 인기 있는 Python 라이브러리입니다.
lazeroffmichael/ticktick-py : 이 프로젝트에서 인증 및 API 상호작용을 처리하는 데 사용하는 비공식 TickTick API 라이브러리입니다.

TickTick MCP Server

Integrations