Donetick MCP 서버

Donetick 잡무 관리를 위한 Model Context Protocol (MCP) 서버입니다. Claude 및 기타 MCP 호환 AI 어시스턴트가 속도 제한 API를 통해 Donetick 인스턴스와 상호작용할 수 있도록 합니다.

기능

• 16개의 MCP 도구: 완전한 잡무 관리 (목록 조회, 조회, 생성, 완료, 업데이트, 삭제, 건너뛰기), 라벨 관리 (목록 조회, 생성, 업데이트, 삭제), 서클 구성원 정보, 사용자 관리 (서클 사용자 목록 조회, 사용자 프로필 조회)

• 전체 API 통합: 모든 엔드포인트가 후행 슬래시로 올바르게 구성된 Donetick 전체 API(/api/v1/) 사용

• 완전한 필드 지원: 빈도 메타데이터, 롤링 일정, 다중 담당자, 할당 전략, 알림, 라벨, 우선순위, 포인트, 하위 작업 등을 포함한 26개 이상의 잡무 생성 필드 모두 작동

• 일관된 필드 표기법: 모든 필드에 걸쳐 camelCase 사용 (name, description, dueDate, createdBy 등)

• 전용 업데이트 도구: 전용 엔드포인트로 잡무 세부 정보, 우선순위, 담당자 업데이트

• JWT 인증: 투명한 갱신으로 자동 토큰 관리

• 스마트 캐싱: get_chore 작업에 대한 지능형 캐싱 (기본 60초 TTL)

• 속도 제한: 토큰 버킷 알고리즘으로 API 과부하 방지

• 재시도 로직: 지터가 포함된 지수 백오프로 탄력적인 작업 수행

• 비동기/대기: httpx를 사용한 논블로킹 작업

• 입력 검증: 살균 처리된 Pydantic 필드 검증기

• 보안 강화: HTTPS 강제, 살균된 로깅, 안전한 오류 메시지, JWT 토큰 보안

• Docker 지원: 보안 모범 사례를 적용한 컨테이너화된 배포

• 포괄적인 테스트: pytest를 사용한 모의 단위/통합 테스트 + 라이브 API 테스트 프레임워크

• 타입 안전성: 요청/응답 검증을 위한 Pydantic 모델

빠른 시작

가장 쉬운 설치 (Claude Code CLI):

claude mcp add donetick uvx donetick-mcp-server@latest

그런 다음 프롬프트에 따라 Donetick 자격 증명을 구성하세요.

또는 uvx로 수동 설치:

# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

장점:

• ✅ 설치 불필요 - PyPI에서 직접 실행

• ✅ --refresh 플래그로 자동 업데이트

• ✅ 격리된 환경 - 충돌 없음

• ✅ Windows, macOS, Linux에서 작동

요구 사항

• Donetick 인스턴스 (자체 호스팅 또는 클라우드)

• Donetick 계정 자격 증명 (사용자 이름 및 비밀번호)

• uvx 방식: uv 설치 필요 (빠른 시작 참조)

• 기타 방식: Python 3.11 이상

설치

옵션 1: uvx (권장 - 설치 불필요)

위의 빠른 시작을 참조하세요.

--refresh 플래그는 Claude Desktop이 다시 시작될 때 항상 최신 버전을 받도록 보장합니다.

옵션 2: Docker

1. 저장소 복제:

   git clone https://github.com/jason1365/donetick-mcp-server.git
   cd donetick-mcp-server

2. .env 파일 생성:

   cp .env.example .env
   # Edit .env with your configuration

3. 환경 변수 구성:

   DONETICK_BASE_URL=https://your-instance.com
   DONETICK_USERNAME=your_username
   DONETICK_PASSWORD=your_password
   LOG_LEVEL=INFO

4. 빌드 및 실행:

   docker-compose build
   docker-compose up -d

옵션 3: pip install (시스템 통합용)

전역 또는 가상 환경에 설치하려는 경우:

# Install from PyPI
pip install donetick-mcp-server

# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .

# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.server

그런 다음 Claude Desktop이 설치된 명령어를 사용하도록 구성:

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

인증

MCP 서버는 Donetick 자격 증명을 사용한 JWT 기반 인증을 사용합니다.

필요한 것:

• Donetick 사용자 이름 (웹 로그인과 동일)

• Donetick 비밀번호 (웹 로그인과 동일)

작동 방식:

1. 서버가 시작 시 자격 증명으로 로그인

2. JWT 토큰을 수신하여 메모리에 저장

3. 토큰이 만료되기 전에 자동으로 갱신

4. 수동 토큰 관리 불필요

보안:

• 자격 증명은 환경 변수 또는 .env 파일에만 저장

• JWT 토큰은 메모리에만 유지 (디스크에 저장되지 않음)

• 자동 토큰 갱신으로 세션 만료 방지

• 모든 연결에 HTTPS 필수

Claude Desktop 통합

가장 쉬운 방법 - Claude Code CLI:

claude mcp add donetick uvx donetick-mcp-server@latest

또는 구성 파일을 수동으로 편집:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

uvx 구성 (권장)

{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

참고: --refresh 플래그는 자동으로 최신 버전으로 업데이트합니다.

Docker 구성

{
  "mcpServers": {
    "donetick": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "donetick-mcp-server",
        "python",
        "-m",
        "donetick_mcp.server"
      ]
    }
  }
}

pip install 구성

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

구성을 업데이트한 후 Claude Desktop을 다시 시작하세요.

사용 가능한 도구

1. list_chores

선택적 필터링으로 모든 잡무를 나열합니다.

매개변수:

• filter_active (boolean, 선택): 활성 상태로 필터링

• assigned_to_user_id (integer, 선택): 할당된 사용자 ID로 필터링

예시:

List all active chores assigned to me

2. get_chore

ID로 특정 잡무의 세부 정보를 조회합니다.

매개변수:

• chore_id (integer, 필수): 잡무 ID

예시:

Show me details of chore 123

3. create_chore

전체 구성 지원으로 새 잡무를 생성합니다.

기본 매개변수:

• name (string, 필수): 잡무 이름 (1-200자)

• description (string, 선택): 잡무 설명 (최대 5000자)

• due_date (string, 선택): YYYY-MM-DD 또는 RFC3339 형식의 마감일

• created_by (integer, 선택): 생성자 사용자 ID

반복/빈도 매개변수:

• frequency_type (string, 선택): 잡무 반복 방식 - "once", "daily", "weekly", "monthly", "yearly", "interval_based" (기본값: "once")

• frequency (integer, 선택): 빈도 배수, 예: 1=매주, 2=격주 (기본값: 1)

• frequency_metadata (object, 선택): 추가 빈도 구성, 예: {"days": [1,3,5], "time": "09:00"}

• is_rolling (boolean, 선택): 롤링 일정 (완료 기준 다음 마감) vs 고정 (기본값: false)

사용자 할당 매개변수:

• assigned_to (integer, 선택): 기본 할당 사용자 ID

• assignees (array, 선택): 여러 할당자, [{"userId": 1}, {"userId": 2}] 형식

• assign_strategy (string, 선택): 할당 전략 - "least_completed", "round_robin", "random" (기본값: "least_completed")

알림 매개변수:

• notification (boolean, 선택): 알림 활성화 (기본값: false)

• nagging (boolean, 선택): 잔소리/리마인더 알림 활성화 (기본값: false)

• predue (boolean, 선택): 마감 전 알림 활성화 (기본값: false)

조직 매개변수:

• priority (integer, 선택): 우선순위 수준 1-5 (1=가장 낮음, 5=가장 높음)

• labels (array, 선택): 라벨 태그, 예: ["cleaning", "outdoor"]

상태 매개변수:

• is_active (boolean, 선택): 활성 상태 - 비활성 잡무는 숨겨짐 (기본값: true)

• is_private (boolean, 선택): 비공개 잡무, 생성자만 볼 수 있음 (기본값: false)

게임화 매개변수:

• points (integer, 선택): 완료 시 지급되는 포인트

고급 매개변수:

• sub_tasks (array, 선택): 하위 작업/체크리스트 항목

예시:

Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10

Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1

Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 points

4. complete_chore

잡무를 완료로 표시합니다.

매개변수:

• chore_id (integer, 필수): 잡무 ID

• completed_by (integer, 선택): 완료한 사용자 ID

예시:

Mark chore 123 as complete

5. delete_chore

잡무를 영구적으로 삭제합니다. 생성자만 삭제할 수 있습니다.

매개변수:

• chore_id (integer, 필수): 잡무 ID

예시:

Delete chore 123

6. get_circle_members

서클(가구/팀)의 모든 구성원을 조회합니다. 잡무를 할당할 수 있는 사람을 보여줍니다.

매개변수: 없음

반환값:

• 사용자 ID

• 사용자 이름

• 표시 이름

• 역할 (admin/member)

• 활성 상태

• 포인트 및 사용 포인트

예시:

Show me who's in my household
Who can I assign chores to?
List all circle members

구성

환경 변수

속도 제한

서버는 API 과부하를 방지하기 위해 토큰 버킷 속도 제한기를 구현합니다:

• 기본값: 초당 10개 요청, 버스트 용량 10

• 보수적: 보수적으로 시작하며 Donetick 인스턴스에 따라 증가 가능

• 429 응답 준수: API에 의해 속도 제한되면 자동으로 백오프

재시도 로직

• 일시적 오류에 대한 지터가 포함된 지수 백오프

• 대부분의 작업에 대해 최대 3회 재시도

• 스마트 재시도: 5xx 오류 및 429(속도 제한)에만 재시도

• 4xx 오류는 재시도하지 않음: 클라이언트 오류는 즉시 실패 (429 제외)

개발

테스트 실행

모의 테스트 (빠름, Donetick 인스턴스 불필요):

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (unit + integration with mocks)
pytest

# Run with coverage
pytest --cov=donetick_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py
pytest tests/test_server.py

# Run with verbose output
pytest -v

라이브 API 테스트 (Donetick 인스턴스 필요):

# Create .env file with credentials (see Configuration section)
# Then run live API integration tests
pytest tests/integration/test_live_api.py -v

# Skip live tests
pytest -m "not live_api"

# Run only live tests
pytest -m live_api

테스트 커버리지 세부사항:

• 모의 테스트는 로직, 재시도 동작, 속도 제한, 오류 처리를 검증

• 라이브 API 테스트는 엔드포인트 라우팅, 필드 표기법 호환성, 응답 형식을 확인

• 전체 커버리지는 API 클라이언트 신뢰성과 MCP 도구 정확성을 모두 보장

프로젝트 구조

donetick-mcp-server/
├── src/donetick_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── client.py           # Donetick API client
│   ├── models.py           # Pydantic data models
│   └── config.py           # Configuration management
├── tests/
│   ├── test_client.py      # API client tests
│   └── test_server.py      # MCP server tests
├── tmp/                    # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

참고: tmp/ 디렉토리는 개발 중 임시 테스트 스크립트 및 분석 파일에 사용됩니다. gitignore에 포함되어 있으며 릴리스에 포함되지 않습니다.

API 문서

이 서버는 JWT 인증을 사용하는 Donetick 전체 API (/api/v1/)를 사용합니다.

공식 리소스

• Donetick 문서: https://docs.donetick.com/

• Donetick GitHub: https://github.com/donetick/donetick

API 아키텍처

사용되는 엔드포인트:

• 잡무 목록 조회: GET /api/v1/chores/ (후행 슬래시 필요)

• 잡무 조회: GET /api/v1/chores/{id} (하위 작업 포함)

• 잡무 생성: POST /api/v1/chores/

• 잡무 업데이트: PUT /api/v1/chores/{id} (name, description, nextDueDate)

• 우선순위 업데이트: PUT /api/v1/chores/{id}/priority

• 담당자 업데이트: PUT /api/v1/chores/{id}/assignee

• 잡무 건너뛰기: PUT /api/v1/chores/{id}/skip

• 잡무 완료: POST /api/v1/chores/{id}/do

• 잡무 삭제: DELETE /api/v1/chores/{id}

• 구성원 조회: GET /api/v1/circles/members/ (후행 슬래시 필요)

중요: 목록 조회 엔드포인트는 후행 슬래시가 필요합니다 (/api/v1/chores/, /api/v1/circles/members/). 클라이언트에서 자동으로 처리됩니다.

중요 참고 사항

1. 전체 API 사용: 외부 API(eAPI)가 아닌 내부 전체 API 사용

2. 필드 표기법: 모든 곳에서 일관된 camelCase (name, description, dueDate, createdBy)

3. 후행 슬래시: 목록 조회 엔드포인트는 올바른 라우팅을 위해 후행 슬래시 포함

4. 인증: 자동 관리되는 JWT Bearer 토큰

5. 완전한 기능 지원: 26개 이상의 잡무 생성 필드 모두 사용 가능

6. 자동 토큰 갱신: JWT 토큰이 투명하게 갱신됨

7. 서클 범위: 모든 작업은 서클(가구/팀) 범위로 제한됨

8. 프리미엄 제한 없음: 전체 API를 통해 모든 기능 사용 가능

문제 해결

일반적인 문제

"DONETICK_BASE_URL 환경 변수가 필요합니다"

• .env 파일이 존재하고 올바르게 형식화되었는지 확인하세요.

• Docker: docker-compose.yml에 환경 변수가 전달되었는지 확인하세요.

"속도 제한됨, 대기 중..."

• 서버가 API 속도 제한을 준수하고 있습니다.

• 자주 발생하는 경우 RATE_LIMIT_PER_SECOND를 줄이는 것을 고려하세요.

"연결 거부됨" 또는 시간 초과 오류

• Donetick 인스턴스 URL이 올바른지 확인하세요.

• Donetick 인스턴스에 접근 가능한지 확인하세요.

• 방화벽 규칙이 아웃바운드 연결을 허용하는지 확인하세요.

"401 Unauthorized" 또는 "Invalid credentials"

• 사용자 이름과 비밀번호가 올바른지 확인하세요.

• 계정이 잠기거나 비활성화되지 않았는지 확인하세요.

• 동일한 자격 증명으로 Donetick 웹 인터페이스에 로그인할 수 있는지 확인하세요.

• 환경 변수에 오타가 있는지 확인하세요.

Claude에서 도구가 표시되지 않는 경우

• 설정 변경 후 Claude Desktop을 다시 시작하세요.

• Claude Desktop 로그에서 오류를 확인하세요.

• 구성 파일 경로가 올바른지 확인하세요.

디버깅

디버그 로깅 활성화:

export LOG_LEVEL=DEBUG

또는 Docker에서:

environment:
  - LOG_LEVEL=DEBUG

Docker 로그 보기:

docker-compose logs -f donetick-mcp

보안

• 자격 증명: 자격 증명을 버전 관리에 커밋하지 마세요 (.env 파일 사용).

• JWT 토큰: 메모리에만 저장되며, 디스크에 기록되지 않습니다.

• 자동 토큰 갱신: 사용자 개입 없이 세션 만료를 방지합니다.

• Docker 격리: 컨테이너에서 비루트 사용자로 실행됩니다.

• 리소스 제한: 메모리 및 CPU 제한으로 리소스 고갈을 방지합니다.

• 입력 검증: Pydantic 모델이 모든 입력을 검증합니다.

• HTTPS 필수: 서버는 모든 Donetick 연결에 대해 HTTPS를 적용합니다.

기여하기

기여를 환영합니다! 다음을 따라주세요:

1. 저장소를 포크하세요.

2. 기능 브랜치를 생성하세요.

3. 새로운 기능에 대한 테스트를 추가하세요.

4. 모든 테스트가 통과하는지 확인하세요.

5. 풀 리퀘스트를 제출하세요.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

감사의 말

• Donetick - 오픈 소스 잡일 관리

• Model Context Protocol - MCP 사양

• Anthropic - MCP SDK 및 Claude

지원

• 이슈: https://github.com/jason1365/donetick-mcp-server/issues

• Donetick 문서: https://docs.donetick.com

• MCP 문서: https://modelcontextprotocol.io

Donetick 및 MCP 커뮤니티를 위해 ❤️로 제작되었습니다.