{"id":27976530,"url":"https://github.com/doist/todoist-mcp","last_synced_at":"2026-05-25T05:01:30.011Z","repository":{"id":309606553,"uuid":"987716578","full_name":"Doist/todoist-mcp","owner":"Doist","description":"A set of tools to connect to AI agents, to allow them to use Todoist on a user's behalf. Includes MCP support.","archived":false,"fork":false,"pushed_at":"2026-05-21T13:46:30.000Z","size":3514,"stargazers_count":492,"open_issues_count":8,"forks_count":48,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-05-21T22:32:02.070Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Doist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-21T13:34:02.000Z","updated_at":"2026-05-21T19:59:30.000Z","dependencies_parsed_at":"2026-04-27T05:00:46.202Z","dependency_job_id":null,"html_url":"https://github.com/Doist/todoist-mcp","commit_stats":null,"previous_names":["doist/todoist-ai","doist/todoist-mcp"],"tags_count":118,"template":false,"template_full_name":null,"purl":"pkg:github/Doist/todoist-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Doist","download_url":"https://codeload.github.com/Doist/todoist-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftodoist-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33458464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T02:24:28.008Z","status":"ssl_error","status_checked_at":"2026-05-25T02:23:23.339Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-08T01:27:41.809Z","updated_at":"2026-05-25T05:01:30.003Z","avatar_url":"https://github.com/Doist.png","language":"TypeScript","funding_links":[],"categories":["Other Tools and Integrations"],"sub_categories":["How to Submit"],"readme":"# Todoist MCP Server\n\n\u003e **Note:** This package was previously named `@doist/todoist-ai`. The old name continues to work as a thin shim that re-exports from `@doist/todoist-mcp`, but new installs should use `@doist/todoist-mcp` directly.\n\nLibrary for connecting AI agents to Todoist. Includes tools that can be integrated into LLMs,\nenabling them to access and modify a Todoist account on the user's behalf.\n\nThese tools can be used both through an MCP server, or imported directly in other projects to\nintegrate them to your own AI conversational interfaces.\n\n## Using tools\n\n### 1. Add this repository as a dependency\n\n```sh\nnpm install @doist/todoist-mcp\n```\n\n### 2. Import the tools and plug them to an AI\n\nHere's an example using [Vercel's AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/generating-text#streamtext).\n\n```js\nimport { findTasksByDate, addTasks } from '@doist/todoist-mcp'\nimport { TodoistApi } from '@doist/todoist-sdk'\nimport { streamText } from 'ai'\n\n// Create Todoist API client\nconst client = new TodoistApi(process.env.TODOIST_API_KEY)\n\n// Helper to wrap tools with the client\nfunction wrapTool(tool, todoistClient) {\n    return {\n        ...tool,\n        execute(args) {\n            return tool.execute(args, todoistClient)\n        },\n    }\n}\n\nconst result = streamText({\n    model: yourModel,\n    system: 'You are a helpful Todoist assistant',\n    tools: {\n        findTasksByDate: wrapTool(findTasksByDate, client),\n        addTasks: wrapTool(addTasks, client),\n    },\n})\n```\n\n## Using as an MCP server\n\n### Quick Start\n\nYou can run the MCP server directly with npx:\n\n```bash\nnpx @doist/todoist-mcp\n```\n\n### Setup Guide\n\nThe Todoist MCP server is available as a streamable HTTP service for easy integration with various AI clients:\n\n**Primary URL (Streamable HTTP):** `https://ai.todoist.net/mcp`\n\n#### Claude Desktop\n\n1. Open Settings → Connectors → Add custom connector\n2. Enter `https://ai.todoist.net/mcp` and complete OAuth authentication\n\n#### Cursor\n\nCreate a configuration file:\n\n- **Global:** `~/.cursor/mcp.json`\n- **Project-specific:** `.cursor/mcp.json`\n\n```json\n{\n    \"mcpServers\": {\n        \"todoist\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"mcp-remote\", \"https://ai.todoist.net/mcp\"]\n        }\n    }\n}\n```\n\nThen enable the server in Cursor settings if prompted.\n\n#### Claude Code (CLI)\n\nThe fastest setup is the official Todoist plugin, which wires up the MCP server for you:\n\n```bash\n/plugin marketplace add doist/todoist-mcp\n/plugin install todoist@doist\n```\n\nOAuth runs in your browser the first time you use a Todoist tool. See [Anthropic's plugin docs](https://code.claude.com/docs/en/plugins-reference) for more.\n\nIf you'd rather configure the MCP server manually, run:\n\n```bash\nclaude mcp add --transport http todoist https://ai.todoist.net/mcp\n```\n\nThen launch `claude`, execute `/mcp`, and select the `todoist` MCP server to authenticate.\n\n#### Visual Studio Code\n\n1. Open Command Palette → MCP: Add Server\n2. Select HTTP transport and use:\n\n```json\n{\n    \"servers\": {\n        \"todoist\": {\n            \"type\": \"http\",\n            \"url\": \"https://ai.todoist.net/mcp\"\n        }\n    }\n}\n```\n\n#### Other MCP Clients\n\n```bash\nnpx -y mcp-remote https://ai.todoist.net/mcp\n```\n\nFor more details on setting up and using the MCP server, including creating custom servers, see [docs/mcp-server.md](docs/mcp-server.md).\n\n## Features\n\nA 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).\n\nThis project is in its early stages. Expect more and/or better tools soon.\n\nNevertheless, 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.\n\nFor our design philosophy, guidelines, and development patterns, see [docs/tool-design.md](docs/tool-design.md).\n\n### Available Tools\n\nFor a complete list of available tools, see the [src/tools](src/tools) directory.\n\n#### OpenAI MCP Compatibility\n\nThis server includes `search` and `fetch` tools that follow the [OpenAI MCP specification](https://platform.openai.com/docs/mcp), 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.\n\n## Dependencies\n\n- MCP server using the official [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#installation)\n- Todoist Typescript API client [@doist/todoist-sdk](https://github.com/Doist/todoist-sdk)\n\n## MCP Server Setup\n\nSee [docs/mcp-server.md](docs/mcp-server.md) for full instructions on setting up the MCP server.\n\n## Local Development Setup\n\nSee [docs/dev-setup.md](docs/dev-setup.md) for full setup instructions and [CONTRIBUTING.md](CONTRIBUTING.md) for contributor workflows and quality checks.\n\n### MCP Apps\n\nThis 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.\n\nSee [docs/mcp-apps.md](docs/mcp-apps.md) for the widget architecture, build pipeline, and development workflow.\n\n### Quick Start\n\nAfter cloning and setting up the repository:\n\n- `npm start` - Build and run the MCP inspector for testing\n- `npm run dev` - Development mode with auto-rebuild and restart\n- `npm run tool:list` - List available tools for direct execution\n- `npm run tool -- \u003ctool-name\u003e '\u003cjson-args\u003e'` - Run a tool directly without MCP\n\nWhen using `npm run tool`, include `--` before tool arguments so npm forwards them to `scripts/run-tool.ts`.\n\nExample check before write operations:\n`npm run tool -- user-info '{}'`\nThis confirms which Todoist account the current `TODOIST_API_KEY` is connected to.\n\n`run-tool` uses `TODOIST_API_KEY` from your `.env` file (created from `.env.example` by `npm run setup`). Use a test account or a temporary project when running write operations to avoid modifying real data.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for:\n\n- Development workflow\n- Running tools directly with `scripts/run-tool.ts`\n- Testing and quality checks\n- Commit conventions\n\n## Releasing\n\nThis project uses [release-please](https://github.com/googleapis/release-please) to automate version management and package publishing.\n\n### How it works\n\n1. Make your changes using [Conventional Commits](https://www.conventionalcommits.org/):\n    - `feat:` for new features (minor version bump)\n    - `fix:` for bug fixes (patch version bump)\n    - `feat!:` or `fix!:` for breaking changes (major version bump)\n    - `docs:` for documentation changes\n    - `chore:` for maintenance tasks\n    - `ci:` for CI changes\n\n2. When commits are pushed to `main`:\n    - Release-please automatically creates/updates a release PR\n    - The PR includes version bump and changelog updates\n    - Review the PR and merge when ready\n\n3. After merging the release PR:\n    - A new GitHub release is automatically created\n    - A new tag is created\n    - The `publish` workflow is triggered\n    - The package is published to npm\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoist%2Ftodoist-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoist%2Ftodoist-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoist%2Ftodoist-mcp/lists"}