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를 사용하세요(권장):

uv pip install things-mcp

달리기

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

things-mcp

옵션 2: 수동 설치

필수 조건

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

1단계: UV 설치

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

curl -LsSf https://astral.sh/uv/install.sh | sh

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

2단계: 이 저장소 복제

git clone https://github.com/hald/things-mcp
cd things-mcp

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

uv venv
uv pip install -r pyproject.toml

4단계: Things 인증 토큰 구성

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

python configure_token.py

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

5단계: Claude Desktop 구성

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

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

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

{
    "mcpServers": {
        "things": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/things-mcp",
                "run",
                "things_server.py"
            ]
        }
    }
}

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 스킴 명령을 승인하는 데 사용됩니다.

사물 인증 토큰을 얻는 방법

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

토큰 구성

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

python configure_token.py

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

개발

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

구현 옵션

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

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

개발 워크플로

개발 환경 설정

# Clone the repository
git clone https://github.com/hald/things-mcp
cd things-mcp

# Set up a virtual environment with development dependencies
uv venv
uv pip install -e ".[dev]"  # Install in development mode with extra dependencies

개발 중 변경 사항 테스트

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

# Test the FastMCP implementation
mcp dev things_fast_server.py

# Or test the traditional implementation
mcp dev things_server.py

PyPI용 패키지 빌드

python -m build

PyPI에 게시

twine upload dist/*

Python 3.12 이상이 필요합니다.

문제 해결

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

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

일반적인 문제

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

로그 확인

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

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log