Things MCP Server

MCP 서버 관련 사항

이 모델 컨텍스트 프로토콜(MCP) 서버를 사용하면 Claude Desktop을 사용하여 Things 앱 의 작업 관리 데이터와 상호 작용할 수 있습니다. Claude에게 작업 생성, 프로젝트 분석, 우선순위 관리 등의 작업을 요청할 수 있습니다.

이 서버는 Things.py 라이브러리와 Things URL Scheme을 활용합니다.

왜 Things MCP인가요?

이 MCP 서버는 작업 관리를 위해 AI의 힘을 활용합니다.

• 자연어 작업 생성 : Claude에게 모든 세부 정보를 자연어로 작성하여 작업을 생성하도록 요청하세요.
• 스마트 작업 분석 : 프로젝트와 생산성 패턴에 대한 통찰력을 얻으세요
• GTD 및 생산성 워크플로 : Claude가 생산성 시스템 구현을 도와드립니다.
• 원활한 통합 : 기존 Things 3 데이터와 직접 작동합니다.

특징

• 모든 주요 일정 목록(받은 편지함, 오늘, 예정된 일정 등)에 액세스할 수 있습니다.
• 프로젝트 및 지역 관리
• 태그 작업
• 고급 검색 기능
• 최근 항목 추적
• 체크리스트를 포함한 자세한 품목 정보
• 중첩된 데이터 지원(영역 내 프로젝트, 프로젝트 내 할 일)

설치 옵션

Things MCP 서버를 설치하고 사용하는 방법은 여러 가지가 있습니다.

옵션 1: PyPI에서 설치(권장)

필수 조건

• 파이썬 3.12+
• 클로드 데스크탑
• Things 3("Things URL 사용"은 설정 -> 일반에서 켜야 함)

설치

지엑스피1

또는 uv를 사용하세요(권장):

달리기

설치 후 서버를 직접 실행할 수 있습니다.

옵션 2: 수동 설치

필수 조건

• 파이썬 3.12+
• 클로드 데스크탑
• Things 3("Things URL 사용"은 설정 -> 일반에서 켜야 함)

1단계: UV 설치

아직 uv를 설치하지 않았다면 설치하세요:

그런 다음 터미널을 다시 시작하세요.

2단계: 이 저장소 복제

3단계: Python 환경 및 종속성 설정

4단계: Things 인증 토큰 구성

구성 도구를 실행하여 Things 인증 토큰을 설정하세요.

이는 MCP 서버가 Things 앱과 상호 작용하는 데 필요한 Things 인증 토큰을 구성하는 과정을 안내합니다.

5단계: Claude Desktop 구성

Claude Desktop 구성 파일을 편집합니다.

구성 파일의 mcpServers 키에 Things 서버를 추가합니다(이러한 파일을 설치한 폴더의 경로를 업데이트해야 합니다).

6단계: Claude Desktop을 다시 시작합니다.

변경 사항을 적용하려면 Claude Desktop 앱을 다시 시작하세요.

Claude Desktop을 사용한 샘플 사용

• "오늘 내 할 일 목록에는 무엇이 있나요?"
• "다음 주 해변 휴가를 위해 짐을 싸야 할 일 목록을 만들고, 짐 싸기 체크리스트를 포함하세요."
• "아이젠하워 매트릭스를 사용하여 현재 할 일을 평가하세요."
• "Things를 사용하여 GTD 스타일의 주간 검토를 도와주세요."

팁

• Claude에서 Things을 사용하는 방법과 영역, 프로젝트, 태그 등을 구성하는 방법을 설명하는 사용자 지정 지침이 있는 프로젝트를 만듭니다. Claude가 새 작업을 만들 때 포함할 정보를 알려줍니다(예: 작업 설명에 관련 세부 정보를 포함하도록 요청하는 것이 도움이 될 수 있음).
• Claude에게 캘린더 접근 권한을 부여하는 다른 MCP 서버를 추가해 보세요. 이렇게 하면 Claude에게 특정 작업을 위해 캘린더에서 시간을 차단하거나, 예정된 캘린더 이벤트(예: 회의 준비)에서 할 일을 만드는 등의 작업을 할 수 있습니다.

사용 가능한 도구

목록 보기

• get-inbox - Inbox에서 할 일 가져오기
• get-today - 오늘 마감일인 할 일 가져오기
• get-upcoming - 예정된 할 일 가져오기
• get-anytime - Anytime 목록에서 할 일 가져오기
• get-someday - Someday 목록에서 할 일 가져오기
• get-logbook - 완료된 할 일 가져오기
• get-trash - 휴지통에 버린 할 일 목록 가져오기

기본 작업

• get-todos - 프로젝트별로 필터링하여 할 일 가져오기
• get-projects - 모든 프로젝트 가져오기
• get-areas - 모든 지역 가져오기

태그 작업

• get-tags - 모든 태그 가져오기
• get-tagged-items - 특정 태그가 있는 항목 가져오기

검색 작업

• search-todos - 제목/메모로 간단 검색
• search-advanced - 여러 필터를 사용한 고급 검색

시간 기반 작업

• get-recent - 최근에 생성된 항목 가져오기

도구 매개변수

할 일 목록

• project_uuid (선택 사항) - 프로젝트별로 할 일 필터링
• include_items (선택 사항, 기본값: true) - 체크리스트 항목 포함

get-projects / get-areas / get-tags

• include_items (선택 사항, 기본값: false) - 포함된 항목 포함

검색-고급

• status - 상태별 필터링(미완료/완료/취소)
• start_date - 시작일(YYYY-MM-DD)로 필터링
• deadline - 마감일(YYYY-MM-DD)로 필터링
• tag - 태그로 필터링
• area - 지역 UUID로 필터링
• type - 항목 유형(할 일/프로젝트/제목)으로 필터링

최근 게시물 가져오기

• period - 기간(예: '3일', '1주', '2개월', '1년')

할 일 추가

• title - 할 일의 제목
• notes (선택 사항) - 할 일에 대한 메모
• when (선택 사항) - 할 일을 언제 예약할지 (오늘, 내일, 저녁, 언제든지, 언젠가 또는 YYYY-MM-DD)
• deadline (선택 사항) - 할 일의 마감일(YYYY-MM-DD)
• tags (선택 사항) - 할 일에 적용할 태그
• list_title 또는 list_id (선택 사항) - 추가할 프로젝트/영역의 제목 또는 ID
• heading (선택 사항) - 추가할 제목
• checklist_items (선택 사항) - 추가할 체크리스트 항목

업데이트-할 일

• id - 업데이트할 todo의 ID
• title (선택 사항) - 새 제목
• notes (선택 사항) - 새로운 노트
• when (선택 사항) - 새 일정
• deadline (선택 사항) - 새로운 마감일
• tags (선택 사항) - 새 태그
• completed (선택 사항) - 완료로 표시
• canceled (선택 사항) - 취소됨으로 표시

프로젝트 추가

• title - 프로젝트 제목
• notes (선택 사항) - 프로젝트에 대한 메모
• when (선택 사항) - 프로젝트를 언제 예약할지
• deadline (선택 사항) - 프로젝트 마감일
• tags (선택 사항) - 프로젝트에 적용할 태그
• area_title 또는 area_id (선택 사항) - 추가할 영역의 제목 또는 ID
• todos (선택 사항) - 프로젝트에서 생성할 초기 todos

업데이트 프로젝트

• id - 업데이트할 프로젝트의 ID
• title (선택 사항) - 새 제목
• notes (선택 사항) - 새로운 노트
• when (선택 사항) - 새 일정
• deadline (선택 사항) - 새로운 마감일
• tags (선택 사항) - 새 태그
• completed (선택 사항) - 완료로 표시
• canceled (선택 사항) - 취소됨으로 표시

쇼 아이템

• id - 표시할 항목의 ID 또는 다음 중 하나: 받은 편지함, 오늘, 예정된 날짜, 언제든지, 언젠가, 일지
• query (선택 사항) - 필터링할 선택 쿼리
• filter_tags (선택 사항) - 필터링할 선택 태그

인증 토큰 구성

Things MCP 서버는 Things 앱과 상호 작용하기 위해 인증 토큰이 필요합니다. 이 토큰은 URL 스킴 명령을 승인하는 데 사용됩니다.

사물 인증 토큰을 얻는 방법

1. Mac에서 Things 앱을 엽니다.
2. 사물 → 환경 설정(⌘,)으로 이동하세요.
3. 일반 탭을 선택하세요
4. "사물 URL 활성화"가 체크되어 있는지 확인하세요.
5. 환경 설정 창에 표시된 인증 토큰을 찾으세요.

토큰 구성

포함된 구성 도구를 실행하여 토큰을 설정하세요.

이 대화형 스크립트는 토큰을 입력하라는 메시지를 표시하고 이를 로컬 구성에 안전하게 저장합니다.

개발

이 프로젝트는 pyproject.toml 사용하여 종속성을 관리하고 구성을 빌드합니다. Claude가 도구와 데이터에 안전하게 액세스할 수 있도록 하는 Model Context Protocol을 사용하여 빌드되었습니다.

구현 옵션

이 프로젝트는 두 가지 다른 구현 접근 방식을 제공합니다.

1. 표준 MCP 서버 ( things_server.py ) - 기본 MCP 서버 패턴을 사용하는 원래 구현입니다.
2. FastMCP 서버 ( things_fast_server.py ) - 데코레이터 기반 도구 등록을 통해 더 깔끔하고 유지 관리하기 쉬운 코드를 제공하는 FastMCP 패턴을 사용한 최신 구현입니다.

개발 워크플로

개발 환경 설정

개발 중 변경 사항 테스트

MCP 개발 서버를 사용하여 변경 사항을 테스트합니다.

PyPI용 패키지 빌드

PyPI에 게시

Python 3.12 이상이 필요합니다.

문제 해결

서버에는 다음에 대한 오류 처리가 포함되어 있습니다.

• 잘못된 UUID
• 필수 매개변수가 없습니다
• 사물 데이터베이스 접근 오류
• 데이터 형식 오류
• 인증 토큰 문제

일반적인 문제

1. 토큰이 누락되었거나 유효하지 않습니다 . python configure_token.py 실행하여 토큰을 설정하세요.
2. Things 앱이 실행되지 않음 : MCP 서버를 사용할 때 Things 3이 열려 있는지 확인하세요.
3. URL 체계가 활성화되지 않았습니다 . Things → 환경 설정 → 일반에서 "Things URL 활성화"가 활성화되어 있는지 확인하세요.

로그 확인

모든 오류는 기록되고 설명 메시지와 함께 반환됩니다. Claude Desktop에서 MCP 로그를 확인하려면 터미널에서 다음 명령어를 실행하세요.