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 자격 증명에 대한 액세스(아래 참조).

설정

1. 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이 환경 변수에 저장되었는지 확인하세요.

2. 환경 변수: 서버에는 방금 얻은 TickTick API 자격 증명과 TickTick 로그인 정보가 필요합니다. 기본적으로 ~/.config/ticktick-mcp/.env 에 있는 .env 파일을 찾습니다.

   • ~/.config/ticktick-mcp/ 디렉토리가 없으면 서버가 직접 생성 할 수도 있지만 , 수동으로 생성하는 것이 더 안전합니다.

   • 해당 디렉토리 내에 .env .

   • 또는 Python을 통해 서버를 직접 실행할 때만 --dotenv-dir 명령줄 인수를 사용하여 다른 디렉터리를 지정할 수 있습니다(아래 "서버 실행" 참조). .env 파일에는 다음이 포함되어야 합니다.

지엑스피1

3. 인증(첫 번째 실행): 첫 번째 실행(직접 또는 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 등)를 구성하여 서버를 사용하세요. 구성 예시:

🔧 도구

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

작업 관리

1. 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 (객체 배열, 선택 사항): 하위 작업 사전 목록입니다.

2. ticktick_update_task

   • 기존 작업을 업데이트합니다

   • 입력:

     • task_object (객체): 작업 id 포함하여 업데이트할 작업 속성이 있는 사전입니다.

3. ticktick_delete_tasks

   • 하나 이상의 작업을 삭제합니다

   • 입력:

     • task_ids (문자열 또는 문자열 배열): 삭제할 단일 작업 ID 또는 작업 ID 목록입니다.

4. ticktick_complete_task

   • 작업을 완료로 표시합니다

   • 입력:

     • task_id (문자열): 완료로 표시할 작업의 ID입니다.

5. ticktick_move_task

   • 작업을 다른 프로젝트로 이동합니다.

   • 입력:

     • task_id (문자열): 이동할 작업의 ID입니다.

     • new_project_id (문자열): 대상 프로젝트의 ID입니다.

6. ticktick_make_subtask

   • 한 작업을 다른 작업의 하위 작업으로 만듭니다.

   • 입력:

     • parent_task_id (문자열): 부모가 될 작업의 ID입니다.

     • child_task_id (문자열): 하위 작업이 될 작업의 ID입니다.

작업 검색

7. ticktick_get_by_id

   • ID로 특정 객체(작업, 프로젝트 등)를 검색합니다.

   • 입력:

     • obj_id (문자열): 검색할 객체의 고유 ID입니다.

8. ticktick_get_all

   • 지정된 유형의 모든 객체를 검색합니다

   • 입력:

     • search (문자열): 검색할 객체의 유형(예: '작업', '프로젝트', '태그').

9. ticktick_get_tasks_from_project

   • 특정 프로젝트에서 완료되지 않은 모든 작업을 검색합니다.

   • 입력:

     • project_id (문자열): 프로젝트의 ID입니다.

10. 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 (문자열, 선택 사항): 날짜 해석을 위한 시간대입니다.

도우미 도구

11. ticktick_convert_datetime_to_ticktick_format

• ISO 8601 날짜/시간 문자열을 TickTick API 형식으로 변환합니다.

• 입력:

  • datetime_iso_string (문자열): ISO 8601 형식의 날짜/시간 문자열입니다.

  • tz (문자열): 날짜/시간을 해석하기 위한 IANA 시간대 이름입니다.

🤖 샘플 에이전트 프롬프트

🤝 기여하기

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

📜 라이센스

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

🔗 또한 참조하세요

• 모델 컨텍스트 프로토콜 서버 : 다양한 도구와 플랫폼을 위한 MCP 서버의 참조 구현을 위한 중앙 저장소입니다.

• modelcontextprotocol.io : 모델 컨텍스트 프로토콜에 대한 공식 문서입니다.

• pietrozullo/mcp-use : MCP 서버와 상호 작용하는 클라이언트/에이전트를 구축하기 위한 인기 있는 Python 라이브러리입니다.

• lazeroffmichael/ticktick-py : 이 프로젝트에서 인증 및 API 상호작용을 처리하는 데 사용하는 비공식 TickTick API 라이브러리입니다.