todoist-v1-mcp-server

깔끔하고 신뢰할 수 있는 Todoist용 MCP(Model Context Protocol) 서버 — Todoist 통합 API v1 기반으로 구축되었습니다.

이 서버가 필요한 이유

공식 Todoist 웹 MCP(todoist-ai)는 Anthropic 측에서 매일 재연결이 필요한 고질적인 연결 끊김 버그가 있습니다. 커뮤니티 대안들은 더 이상 사용되지 않는 REST API v2를 기반으로 하거나, Todoist API가 발전함에 따라 추가 필드가 반환될 때 스키마 유효성 검사 오류로 인해 실패하는 문제가 있습니다.

이 서버의 특징:

• 현재 Todoist API v1을 타겟팅합니다 (더 이상 사용되지 않는 v2 아님)

• stdio 전송 사용 — 클라우드 의존성 없음, 매일 재연결할 필요 없음

• 최신 MCP SDK registerTool() API 사용 (더 이상 사용되지 않는 setRequestHandler 패턴 아님)

• API 응답에 대해 엄격한 출력 스키마를 강제하지 않음 — Todoist가 새로운 필드를 추가해도 아무것도 깨지지 않음

• SDK 래퍼 의존성 제로 — axios를 통한 직접적인 HTTP 호출을 사용하므로 API와 동떨어진 중간 라이브러리가 없음

도구 (총 20개)

작업 (Tasks)

프로젝트 (Projects)

섹션 (Sections)

라벨 (Labels)

설정

1. Todoist API 토큰 가져오기

Todoist → 설정 → 통합 → 개발자로 이동하여 API 토큰을 복사하세요.

2. 설치 및 빌드

git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build

3. Claude Desktop 구성

~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집하세요:

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-v1-mcp-server/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Claude Desktop을 다시 시작하세요. 연결된 MCP 서버에 "todoist"가 표시되어야 합니다.

4. Claude Code 구성 (선택 사항)

claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js

그런 다음 환경 변수를 설정하세요:

export TODOIST_API_TOKEN=your_api_token_here

또는 셸 프로필에 추가하세요.

사용 예시

연결되면 Claude는 다음과 같은 자연어를 처리할 수 있습니다:

• "오늘 할 일이 뭐야?" → filter: "today"와 함께 todoist_get_tasks 사용

• "다음 주 화요일에 치과에 가라는 작업 추가해줘" → todoist_create_task 사용

• "치과 작업 완료로 표시해줘" → todoist_complete_task 사용

• "기한이 지난 모든 작업 보여줘" → filter: "overdue"와 함께 todoist_get_tasks 사용

• "집 수리라는 프로젝트를 만들어줘" → todoist_create_project 사용

• "내 프로젝트가 뭐가 있지?" → todoist_get_projects 사용

Todoist 필터 구문

todoist_get_tasks의 filter 매개변수는 Todoist의 전체 자연어 필터 구문을 지원합니다:

전체 필터 문서: https://todoist.com/help/articles/introduction-to-filters

요구 사항

• Node.js 18 이상

• Todoist 계정 (무료 티어 가능)

개발

npm run dev   # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start     # run compiled server

테스트

테스트 스위트는 실제 Todoist API를 호출하며 작업, 프로젝트, 섹션, 라벨 전반에 걸쳐 전체 CRUD 주기를 실행합니다. 모든 테스트 데이터는 [mcp-test] 접두사가 붙으며 자동으로 정리됩니다.

TODOIST_API_TOKEN=your_token npm test

API 토큰은 Todoist → 설정 → 통합 → 개발자에 있으며, claude_desktop_config.json에 넣은 것과 동일한 토큰입니다.

기여

PR을 환영합니다. 목표는 Todoist API v1을 최신 상태로 유지하는 최소한의 올바른 구현입니다. 우선순위:

1. 기교보다 정확성

2. 관대한 출력 처리 (알 수 없는 API 필드를 절대 거부하지 않음)

3. 무엇이 잘못되었고 어떻게 해결해야 하는지 알려주는 유용한 오류 메시지

라이선스

MIT