Todoist MCP

Server MCP Todoist

Pustaka untuk menghubungkan agen AI ke Todoist. Termasuk alat yang dapat diintegrasikan ke dalam LLM, memungkinkan mereka untuk mengakses dan memodifikasi akun Todoist atas nama pengguna.

Alat-alat ini dapat digunakan baik melalui server MCP, atau diimpor langsung ke proyek lain untuk mengintegrasikannya ke antarmuka percakapan AI Anda sendiri.

Menggunakan alat

1. Tambahkan repositori ini sebagai dependensi

npm install @doist/todoist-mcp

2. Impor alat dan hubungkan ke AI

Berikut contoh menggunakan Vercel's 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),
    },
})

Menggunakan sebagai server MCP

Memulai Cepat

Anda dapat menjalankan server MCP langsung dengan npx:

npx @doist/todoist-mcp

Panduan Pengaturan

Server MCP Todoist tersedia sebagai layanan HTTP yang dapat dialirkan untuk integrasi mudah dengan berbagai klien AI:

URL Utama (HTTP yang Dapat Dialirkan): https://ai.todoist.net/mcp

Claude Desktop

1. Buka Pengaturan → Konektor → Tambahkan konektor khusus
2. Masukkan https://ai.todoist.net/mcp dan selesaikan autentikasi OAuth

Cursor

Buat file konfigurasi:

• Global: ~/.cursor/mcp.json
• Khusus proyek: .cursor/mcp.json

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

Kemudian aktifkan server di pengaturan Cursor jika diminta.

Claude Code (CLI)

Pengaturan tercepat adalah plugin resmi Todoist, yang menyiapkan server MCP untuk Anda:

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

OAuth berjalan di browser Anda saat pertama kali menggunakan alat Todoist. Lihat dokumentasi plugin Anthropic untuk informasi lebih lanjut.

Jika Anda lebih suka mengonfigurasi server MCP secara manual, jalankan:

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

Kemudian luncurkan claude, jalankan /mcp, dan pilih server MCP todoist untuk mengautentikasi.

Visual Studio Code

1. Buka Palet Perintah → MCP: Tambahkan Server
2. Pilih transport HTTP dan gunakan:

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

Klien MCP Lainnya

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

Untuk detail lebih lanjut tentang menyiapkan dan menggunakan server MCP, termasuk membuat server khusus, lihat docs/mcp-server.md.

Fitur

Fitur utama dari proyek ini adalah alat dapat digunakan kembali, dan tidak ditulis khusus untuk digunakan di server MCP. Alat-alat tersebut dapat dihubungkan sebagai alat ke antarmuka AI percakapan lainnya (misalnya Vercel's AI SDK).

Proyek ini masih dalam tahap awal. Harapkan lebih banyak dan/atau alat yang lebih baik segera.

Meskipun demikian, tujuan kami adalah menyediakan seperangkat alat kecil yang memungkinkan alur kerja lengkap, bukan hanya tindakan atomik, menyeimbangkan fleksibilitas dan efisiensi untuk LLM.

Untuk filosofi desain, pedoman, dan pola pengembangan kami, lihat docs/tool-design.md.

Alat yang Tersedia

Untuk daftar lengkap alat yang tersedia, lihat direktori src/tools.

Kompatibilitas MCP OpenAI

Server ini menyertakan alat search dan fetch yang mengikuti spesifikasi MCP OpenAI, memungkinkan integrasi yang mulus dengan protokol MCP OpenAI. Alat-alat ini mengembalikan hasil yang dikodekan JSON yang dioptimalkan untuk kebutuhan OpenAI sambil mempertahankan kompatibilitas dengan ekosistem MCP yang lebih luas.

Dependensi

• Server MCP menggunakan @modelcontextprotocol/server resmi
• Klien API Typescript Todoist @doist/todoist-sdk

Pengaturan Server MCP

Lihat docs/mcp-server.md untuk instruksi lengkap tentang menyiapkan server MCP.

Pengaturan Pengembangan Lokal

Lihat docs/dev-setup.md untuk instruksi pengaturan lengkap dan CONTRIBUTING.md untuk alur kerja kontributor dan pemeriksaan kualitas.

Aplikasi MCP

Proyek ini mencakup dukungan untuk Aplikasi MCP – widget UI interaktif yang dirender sebaris di antarmuka obrolan AI. Widget menyediakan representasi visual yang kaya dari keluaran alat (misalnya, daftar tugas) alih-alih teks biasa.

Lihat docs/mcp-apps.md untuk arsitektur widget, pipeline build, dan alur kerja pengembangan.

Memulai Cepat

Setelah mengkloning dan menyiapkan repositori:

• npm start - Bangun dan jalankan inspektur MCP untuk pengujian
• npm run dev - Mode pengembangan dengan build ulang dan mulai ulang otomatis
• npm run tool:list - Daftar alat yang tersedia untuk eksekusi langsung
• npm run tool -- <tool-name> '<json-args>' - Jalankan alat secara langsung tanpa MCP

Saat menggunakan npm run tool, sertakan -- sebelum argumen alat agar npm meneruskannya ke scripts/run-tool.ts.

Contoh pemeriksaan sebelum operasi tulis: npm run tool -- user-info '{}' Ini mengonfirmasi akun Todoist mana yang terhubung dengan TODOIST_API_KEY saat ini.

run-tool menggunakan TODOIST_API_KEY dari file .env Anda (dibuat dari .env.example oleh npm run setup). Gunakan akun uji atau proyek sementara saat menjalankan operasi tulis untuk menghindari modifikasi data nyata.

Berkontribusi

Lihat CONTRIBUTING.md untuk:

• Alur kerja pengembangan
• Menjalankan alat secara langsung dengan scripts/run-tool.ts
• Pengujian dan pemeriksaan kualitas
• Konvensi commit

Rilis

Proyek ini menggunakan release-please untuk mengotomatiskan manajemen versi dan penerbitan paket.

Cara kerjanya

1. Buat perubahan Anda menggunakan Conventional Commits:

   • feat: untuk fitur baru (kenaikan versi minor)
   • fix: untuk perbaikan bug (kenaikan versi patch)
   • feat!: atau fix!: untuk perubahan yang merusak (kenaikan versi mayor)
   • docs: untuk perubahan dokumentasi
   • chore: untuk tugas pemeliharaan
   • ci: untuk perubahan CI

2. Saat commit didorong ke main:

   • Release-please secara otomatis membuat/memperbarui PR rilis
   • PR menyertakan kenaikan versi dan pembaruan changelog
   • Tinjau PR dan gabungkan saat siap

3. Setelah menggabungkan PR rilis:

   • Rilis GitHub baru dibuat secara otomatis
   • Tag baru dibuat
   • Alur kerja publish dipicu
   • Paket diterbitkan ke npm