Todoist MCP

공식

LLM에서 직접 Todoist 작업과 프로젝트를 관리하세요.

GitHub

541

이 MCP 사용해 보기스폰서

Todoist MCP(으)로 무엇을 할 수 있나요?

날짜별 작업 찾기 — 특정 날짜에 예정된 작업을 찾으려면 어시스턴트에게 findTasksByDate를 사용하도록 요청하세요.
새 작업 추가 — addTasks 도구를 통해 어시스턴트가 Todoist 작업을 하나 이상 생성하게 하세요.
계정 신원 확인 — 변경하기 전에 어떤 Todoist 계정이 연결되어 있는지 묻고, user-info를 사용하여 활성 사용자를 확인하세요.
도구 직접 실행 — npm run tool을 사용하여 JSON 인수로 모든 도구를 독립 실행하고, MCP 서버를 우회하세요.

문서

Todoist MCP 서버

AI 에이전트를 Todoist에 연결하기 위한 라이브러리입니다. LLM에 통합할 수 있는 도구들이 포함되어 있어, 사용자를 대신해 Todoist 계정에 접근하고 수정할 수 있습니다.

이 도구들은 MCP 서버를 통해 사용하거나, 다른 프로젝트에 직접 가져와 자체 AI 대화 인터페이스에 통합할 수 있습니다.

도구 사용하기

1. 이 저장소를 의존성으로 추가

npm install @doist/todoist-mcp

2. 도구를 가져와 AI에 연결

다음은 Vercel의 AI SDK를 사용한 예시입니다.

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/todoist-sdk'
import { streamText } from 'ai'

// Create Todoist API client
const client = new TodoistApi(process.env.TODOIST_API_KEY)

// Helper to wrap tools with the client
function wrapTool(tool, todoistClient) {
    return {
        ...tool,
        execute(args) {
            return tool.execute(args, todoistClient)
        },
    }
}

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Todoist assistant',
    tools: {
        findTasksByDate: wrapTool(findTasksByDate, client),
        addTasks: wrapTool(addTasks, client),
    },
})

MCP 서버로 사용하기

빠른 시작

npx로 MCP 서버를 직접 실행할 수 있습니다:

npx @doist/todoist-mcp

설정 가이드

Todoist MCP 서버는 다양한 AI 클라이언트와 쉽게 통합할 수 있도록 스트리밍 가능한 HTTP 서비스로 제공됩니다:

기본 URL (Streamable HTTP): https://ai.todoist.net/mcp

Claude Desktop

설정 → 커넥터 → 사용자 지정 커넥터 추가를 엽니다
https://ai.todoist.net/mcp를 입력하고 OAuth 인증을 완료합니다

Cursor

구성 파일을 생성합니다:

전역: ~/.cursor/mcp.json
프로젝트별: .cursor/mcp.json

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

그런 다음 메시지가 표시되면 Cursor 설정에서 서버를 활성화합니다.

Claude Code (CLI)

가장 빠른 설정 방법은 공식 Todoist 플러그인을 사용하는 것입니다. 이 플러그인이 MCP 서버를 자동으로 연결해 줍니다:

/plugin marketplace add doist/todoist-mcp
/plugin install todoist@doist

Todoist 도구를 처음 사용할 때 브라우저에서 OAuth가 실행됩니다. 자세한 내용은 Anthropic의 플러그인 문서를 참조하세요.

MCP 서버를 수동으로 구성하려면 다음을 실행하세요:

claude mcp add --transport http todoist https://ai.todoist.net/mcp

그런 다음 claude를 실행하고, /mcp를 실행한 후, todoist MCP 서버를 선택하여 인증합니다.

Visual Studio Code

명령 팔레트 → MCP: 서버 추가를 엽니다
HTTP 전송을 선택하고 다음을 사용합니다:

{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

기타 MCP 클라이언트

npx -y mcp-remote https://ai.todoist.net/mcp

MCP 서버 설정 및 사용에 대한 자세한 내용(사용자 지정 서버 생성 포함)은 docs/mcp-server.md를 참조하세요.

기능

이 프로젝트의 주요 특징은 도구가 재사용 가능하며 MCP 서버에서만 사용하도록 특별히 작성되지 않았다는 점입니다. 다른 대화형 AI 인터페이스(예: Vercel의 AI SDK)의 도구로 연결할 수 있습니다.

이 프로젝트는 초기 단계에 있습니다. 곧 더 많고 더 나은 도구가 추가될 예정입니다.

그럼에도 불구하고, 우리의 목표는 단순한 원자적 작업이 아닌 완전한 워크플로우를 가능하게 하는 소수의 도구를 제공하여 LLM의 유연성과 효율성 사이의 균형을 맞추는 것입니다.

설계 철학, 지침 및 개발 패턴에 대해서는 docs/tool-design.md를 참조하세요.

사용 가능한 도구

사용 가능한 도구의 전체 목록은 src/tools 디렉토리를 참조하세요.

OpenAI MCP 호환성

이 서버에는 OpenAI MCP 사양을 따르는 search 및 fetch 도구가 포함되어 있어 OpenAI의 MCP 프로토콜과 원활하게 통합됩니다. 이 도구들은 OpenAI의 요구 사항에 최적화된 JSON 인코딩 결과를 반환하면서도 더 넓은 MCP 생태계와의 호환성을 유지합니다.

의존성

공식 @modelcontextprotocol/server를 사용하는 MCP 서버
Todoist Typescript API 클라이언트 @doist/todoist-sdk

MCP 서버 설정

MCP 서버 설정에 대한 전체 지침은 docs/mcp-server.md를 참조하세요.

로컬 개발 설정

전체 설정 지침은 docs/dev-setup.md를, 기여자 워크플로우 및 품질 검사는 CONTRIBUTING.md를 참조하세요.

MCP 앱

이 프로젝트는 MCP 앱을 지원합니다. MCP 앱은 AI 채팅 인터페이스에 인라인으로 렌더링되는 대화형 UI 위젯입니다. 위젯은 일반 텍스트 대신 도구 출력(예: 작업 목록)의 풍부한 시각적 표현을 제공합니다.

위젯 아키텍처, 빌드 파이프라인 및 개발 워크플로우는 docs/mcp-apps.md를 참조하세요.

빠른 시작

저장소를 클론하고 설정한 후:

npm start - 테스트용 MCP 인스펙터 빌드 및 실행
npm run dev - 자동 재빌드 및 재시작이 포함된 개발 모드
npm run tool:list - 직접 실행할 수 있는 도구 목록 표시
npm run tool -- <tool-name> '<json-args>' - MCP 없이 도구 직접 실행

npm run tool를 사용할 때는 npm이 scripts/run-tool.ts에 전달할 수 있도록 도구 인수 앞에 --를 포함하세요.

쓰기 작업 전 확인 예시: npm run tool -- user-info '{}' 이렇게 하면 현재 TODOIST_API_KEY가 연결된 Todoist 계정을 확인할 수 있습니다.

run-tool는 .env 파일(.env.example에서 npm run setup로 생성)의 TODOIST_API_KEY를 사용합니다. 실제 데이터를 수정하지 않도록 쓰기 작업을 실행할 때는 테스트 계정이나 임시 프로젝트를 사용하세요.

기여

CONTRIBUTING.md에서 다음을 확인하세요:

개발 워크플로우
scripts/run-tool.ts로 도구 직접 실행
테스트 및 품질 검사
커밋 규칙

릴리스

이 프로젝트는 release-please를 사용하여 버전 관리 및 패키지 게시를 자동화합니다.

작동 방식

Conventional Commits을 사용하여 변경 사항을 만듭니다:
- feat: - 새로운 기능 (부 버전 증가)
- fix: - 버그 수정 (패치 버전 증가)
- feat!: 또는 fix!: - 주요 변경 사항 (주 버전 증가)
- docs: - 문서 변경
- chore: - 유지 관리 작업
- ci: - CI 변경
커밋이 main에 푸시되면:
- Release-please가 자동으로 릴리스 PR을 생성/업데이트합니다
- PR에는 버전 증가 및 변경 로그 업데이트가 포함됩니다
- PR을 검토하고 준비되면 병합합니다
릴리스 PR 병합 후:
- 새 GitHub 릴리스가 자동으로 생성됩니다
- 새 태그가 생성됩니다
- publish 워크플로우가 트리거됩니다
- 패키지가 npm에 게시됩니다