Doist / todoist-ai

Todoist AI and MCP SDK Library for connecting AI agents to Todoist. Includes tools that can be integrated into LLMs, enabling them to access and modify a Todoist account on the user's behalf. These tools can be used both through an MCP server, or imported directly in other projects to integrate them to your own AI conversational interfaces. Using tools • Add this repository as a dependency • Import the tools and plug them to an AI Here's an example using Vercel's AI SDK. Using as an MCP server Quick Start You can run the MCP server directly with npx: Setup Guide The Todoist AI MCP server is available as a streamable HTTP service for easy integration with various AI clients: **Primary URL (Streamable HTTP):** Claude Desktop • Open Settings → Connectors → Add custom connector • Enter and complete OAuth authentication Cursor Create a configuration file: • **Global:** • **Project-specific:** Then enable the server in Cursor settings if prompted. Claude Code (CLI) Firstly configure Claude so it has a new MCP available using this command: Then launch , execute , then select the MCP server. This will take you through a wizard to authenticate using your browser with Todoist. Once complete you will be able to use todoist in . Visual Studio Code • Open Command Palette → MCP: Add Server • Select HTTP transport and use: Other MCP Clients For more details on setting up and using the MCP server, including creating custom servers, see docs/mcp-server.md. Features A key feature of this project is that tools can be reused, and are not written specifically for use in an MCP server. They can be hooked up as tools to other conversational AI interfaces (e.g. Vercel's AI SDK). This project is in its early stages. Expect more and/or better tools soon. Nevertheless, our goal is to provide a small set of tools that enable complete workflows, rather than just atomic actions, striking a balance between flexibility and efficiency for LLMs. For our design philosophy, guidelines, and development patterns, see docs/tool-design.md. Available Tools For a complete list of available tools, see the src/tools directory. OpenAI MCP Compatibility This server includes and tools that follow the OpenAI MCP specification, enabling seamless integration with OpenAI's MCP protocol. These tools return JSON-encoded results optimized for OpenAI's requirements while maintaining compatibility with the broader MCP ecosystem. Dependencies • MCP server using the official @modelcontextprotocol/sdk • Todoist Typescript API client @doist/todoist-api-typescript MCP Server Setup See docs/mcp-server.md for full instructions on setting up the MCP server. Local Development Setup See docs/dev-setup.md for full setup instructions and CONTRIBUTING.md for contributor workflows and quality checks. Widgets This project includes support for **MCP Apps** – interactive UI widgets rendered inline in AI chat interfaces. Widgets provide rich visual representations of tool outputs (e.g., task lists) instead of plain text. See docs/widgets.md for the widget architecture, build pipeline, and development workflow. Quick Start After cloning and setting up the repository: • - Build and run the MCP inspector for testing • - Development mode with auto-rebuild and restart • - List available tools for direct execution • - Run a tool directly without MCP When using , include before tool arguments so npm forwards them to . Example check before write operations: This confirms which Todoist account the current is connected to. uses from your file (created from by ). Use a test account or a temporary project when running write operations to avoid modifying real data. Contributing See CONTRIBUTING.md for: • Development workflow • Running tools directly with • Testing and quality checks • Commit conventions Releasing This project uses release-please to automate version management and package publishing. How it works • Make your changes using Conventional Commits: • for new features (minor version bump) • for bug fixes (patch version bump) • or for breaking changes (major version bump) • for documentation changes • for maintenance tasks • for CI changes • When commits are pushed to : • Release-please automatically creates/updates a release PR • The PR includes version bump and changelog updates • Review the PR and merge when ready • After merging the release PR: • A new GitHub release is automatically created • A new tag is created • The workflow is triggered • The package is published to npm