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 tointegrate them to your own AI conversational interfaces.

npm install @doist/todoist-ai

Here's an example usingVercel's AI SDK.

import{findTasksByDate,addTasks}from"@doist/todoist-ai";import{streamText}from"ai";constresult=streamText({model:yourModel,system:"You are a helpful Todoist assistant",tools:{        findTasksByDate,        addTasks,},});

You can run the MCP server directly with npx:

npx @doist/todoist-ai

The Todoist AI MCP server is available as a streamable HTTP service for easy integration with various AI clients:

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

1. Open Settings → Connectors → Add custom connector
2. Enterhttps://ai.todoist.net/mcp and complete OAuth authentication

Create a configuration file:

• Global:~/.cursor/mcp.json
• Project-specific:.cursor/mcp.json

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

Then enable the server in Cursor settings if prompted.

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

1. Open Command Palette → MCP: Add Server
2. Select HTTP transport and use:

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

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

For more details on setting up and using the MCP server, including creating custom servers, seedocs/mcp-server.md.

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, seedocs/tool-design.md.

For a complete list of available tools, see thesrc/tools directory.

This server includessearch andfetch tools that follow theOpenAI 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.

• MCP server using the official@modelcontextprotocol/sdk
• Todoist Typescript API client@doist/todoist-api-typescript

Seedocs/mcp-server.md for full instructions on setting up the MCP server.

Seedocs/dev-setup.md for full instructions on setting up this repository locally for development and contributing.

After cloning and setting up the repository:

• npm start - Build and run the MCP inspector for testing
• npm run dev - Development mode with auto-rebuild and restart

This project usesrelease-please to automate version management and package publishing.

1. Make your changes usingConventional Commits:

   • feat: for new features (minor version bump)
   • fix: for bug fixes (patch version bump)
   • feat!: orfix!: for breaking changes (major version bump)
   • docs: for documentation changes
   • chore: for maintenance tasks
   • ci: for CI changes

2. When commits are pushed tomain:

   • Release-please automatically creates/updates a release PR
   • The PR includes version bump and changelog updates
   • Review the PR and merge when ready

3. After merging the release PR:

   • A new GitHub release is automatically created
   • A new tag is created
   • Thepublish workflow is triggered
   • The package is published to npm

Todoist

ByDoist·120

A set of tools to connect to AI agents, to allow them to use Todoist on a user's behalf.