{
  "markdown": "# Todoist MCP Server\n\nA Model Context Protocol (MCP) server for Todoist task management, enabling Claude to interact with your Todoist tasks and projects.\n\n## Features\n\n- ✅ Create, read, update, and complete tasks\n- 📋 List tasks with advanced filtering\n- 🔍 Search tasks by text content\n- 📁 Manage projects\n- 🏷️ Support for labels and priorities\n- 📅 Natural language date parsing\n- ⚡ Rate limiting to stay within API limits\n- 🛡️ Comprehensive error handling\n\n## Installation\n\n### Prerequisites\n\n- Node.js >= 18.0.0\n- npm or yarn\n- A Todoist account with an API token\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone <your-repo-url>\ncd todoist-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Configuration\n\n### 1. Get Your Todoist API Token\n\n1. Go to [Todoist Integrations Settings](https://todoist.com/app/settings/integrations/developer)\n2. Scroll down to \"API token\" section\n3. Copy your personal API token\n\n### 2. Set Up Environment Variables\n\nCreate a `.env` file in the project root:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your Todoist API token:\n\n```bash\nTODOIST_API_TOKEN=your_actual_token_here\nLOG_LEVEL=error\n```\n\n### 3. Configure Claude Desktop\n\nAdd the server to your Claude Desktop configuration file:\n\n**Location:**\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n**Configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"todoist\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/todoist-mcp/build/server.js\"],\n      \"env\": {\n        \"TODOIST_API_TOKEN\": \"your_actual_token_here\"\n      }\n    }\n  }\n}\n```\n\n**Important:** Replace `/absolute/path/to/todoist-mcp` with the actual absolute path to your project directory.\n\n### 4. Restart Claude Desktop\n\nAfter updating the configuration, restart Claude Desktop for the changes to take effect.\n\n## Available Tools\n\n### todoist_create_task\n\nCreate a new task in Todoist with optional project, due date, priority, labels, and parent task for subtasks.\n\n**Parameters:**\n\n- `content` (required): The task content/title\n- `description` (optional): Task description\n- `project_id` (optional): Project ID to add the task to\n- `section_id` (optional): Section ID within the project\n- `due_date` (optional): Due date in natural language or YYYY-MM-DD format\n- `priority` (optional): Priority level: 1 (normal), 2 (medium), 3 (high), 4 (urgent)\n- `labels` (optional): Array of label names\n- `parent_id` (optional): Parent task ID to create a subtask\n- `parent_task_name` (optional): Parent task name to search for (alternative to parent_id)\n\n**Examples:**\n\n```\nCreate a task \"Write report\" due tomorrow with high priority\nCreate a task \"Buy groceries\" in the Shopping project\nCreate a task \"Team meeting\" due \"next Monday at 2pm\"\nCreate a subtask \"Buy milk\" under parent task \"Go to the supermarket\"\nCreate a subtask \"Review slides\" under task 8237492837\nAdd subtask \"Call John\" to the task \"Prepare presentation\"\n```\n\n### todoist_list_tasks\n\nList active tasks with optional filters for project, section, label, or custom Todoist filter.\n\n**Parameters:**\n\n- `project_id` (optional): Filter by project ID\n- `section_id` (optional): Filter by section ID\n- `label` (optional): Filter by label name\n- `filter` (optional): Todoist filter query (e.g., \"today\", \"overdue\", \"p1\")\n- `limit` (optional): Maximum number of tasks to return (default: 50, max: 200)\n\n**Examples:**\n\n```\nList all my tasks\nList tasks in project \"Work\"\nList tasks due today\nList all overdue tasks with limit 20\n```\n\n### todoist_get_task\n\nGet detailed information about a specific task including all metadata.\n\n**Parameters:**\n\n- `task_id` (required): The task ID to retrieve\n\n**Examples:**\n\n```\nGet details for task 123456789\nShow me task 987654321\n```\n\n### todoist_update_task\n\nUpdate an existing task with new content, description, due date, priority, or labels.\n\n**Parameters:**\n\n- `task_id` (required): The task ID to update\n- `content` (optional): New task content\n- `description` (optional): New task description\n- `due_date` (optional): New due date (natural language or YYYY-MM-DD)\n- `priority` (optional): New priority level (1-4)\n- `labels` (optional): New labels array\n\n**Examples:**\n\n```\nUpdate task 123 to have priority 4\nChange task 456 due date to \"next Friday\"\nUpdate task 789 content to \"Revised meeting agenda\"\n```\n\n### todoist_complete_task\n\nMark a task as completed.\n\n**Parameters:**\n\n- `task_id` (required): The task ID to complete\n\n**Examples:**\n\n```\nComplete task 123456\nMark task 789012 as done\n```\n\n### todoist_list_projects\n\nList all projects in Todoist, including inbox and shared projects.\n\n**Parameters:** None\n\n**Examples:**\n\n```\nList all my projects\nShow me all my Todoist projects\n```\n\n### todoist_search_tasks\n\nSearch for tasks by text in their content or description.\n\n**Parameters:**\n\n- `query` (required): Text to search for in task content and description\n- `limit` (optional): Maximum number of tasks to return (default: 50, max: 200)\n\n**Examples:**\n\n```\nSearch for tasks containing \"meeting\"\nFind all tasks with \"budget\" in them\n```\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Development Mode (Watch)\n\n```bash\nnpm run dev\n```\n\n### Run Tests\n\n```bash\nnpm test\n```\n\n### Run Tests in Watch Mode\n\n```bash\nnpm run test:watch\n```\n\n## Rate Limits\n\nThe server respects Todoist's API rate limit of **450 requests per 15 minutes**. When the limit is exceeded, the API returns a 429 error which is caught and reported with a helpful error message. You can retry your request after waiting.\n\n## Error Handling\n\nAll errors are returned with descriptive messages. Common errors include:\n\n- **Invalid API token**: Check your `.env` configuration or Claude Desktop config\n- **Task not found**: Verify the task ID exists and hasn't been deleted\n- **Rate limit exceeded**: Wait 15 minutes or reduce request frequency\n- **Network error**: Check your internet connection\n- **Validation error**: Review the parameters you're providing to the tool\n\n## Natural Language Date Support\n\nThe server supports Todoist's natural language date parsing. You can use phrases like:\n\n- \"tomorrow\"\n- \"next Monday\"\n- \"every Friday\"\n- \"in 3 days\"\n- \"next week\"\n- \"Dec 25\"\n\nYou can also use standard date formats:\n\n- \"2024-12-31\"\n- \"2024-12-31T14:30:00\"\n\n## Project Structure\n```\n\ntodoist-mcp/\n├── src/\n│   ├── server.ts           # Main MCP server entry point\n│   ├── types/              # TypeScript type definitions\n│   ├── api/                # Todoist API client and errors\n│   ├── tools/              # MCP tool implementations\n│   └── utils/              # Utilities (logger, rate limiter)\n├── tests/\n│   └── unit/               # Unit tests\n├── build/                  # Compiled JavaScript output\n├── package.json\n├── tsconfig.json\n├── .env.example\n└── README.md\n```\n\n## Publishing & Registry\n\n- **MCP name:** `io.github.ecfaria/todoist-mcp`\n- **NPM package:** `@ecfaria/todoist-mcp-server`\n- **server.json:** see the root of this repo for the registry definition\n\n### Publishing flow\n\n1. Update version numbers as needed (`npm version <patch|minor|major>`).\n2. Build the distributable: `npm run build`.\n3. Publish to npm: `npm publish --access public` (scoped packages default to private).\n4. Validate registry metadata: `mcp-publisher validate`.\n5. Publish to the MCP registry: `mcp-publisher publish`.\n\n### Release notes (v1.0.0)\n\n- Added MCP registry metadata (`mcpName`) to `package.json`.\n- Documented the publishing process and registry identity.\n- Introduced the canonical `server.json` reference for registry publication.\n- Adopted the scoped npm package name `@ecfaria/todoist-mcp-server` to avoid collisions.\n\n## Troubleshooting\n\n### Server not showing in Claude\n\n1. Verify the path in `claude_desktop_config.json` is absolute and correct\n2. Check that you've built the project (`npm run build`)\n3. Ensure the API token is set in the config\n4. Restart Claude Desktop completely\n\n### API Token Invalid\n\n1. Go to [Todoist Integrations Settings](https://todoist.com/app/settings/integrations/developer)\n2. Generate a new API token\n3. Update your `.env` file or Claude Desktop config\n4. Restart the server/Claude Desktop\n\n### Tasks Not Showing Up\n\n1. Verify you're using the correct project ID or filter\n2. Check that tasks aren't already completed\n3. Try listing all tasks without filters to see what's available\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT\n\n## Support\n\n- [Todoist API Documentation](https://developer.todoist.com/rest/v2/)\n- [MCP Documentation](https://modelcontextprotocol.io/)\n- [GitHub Issues](https://github.com/yourusername/todoist-mcp/issues)\n\n## Acknowledgments\n\nBuilt with:\n\n- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [Todoist REST API v2](https://developer.todoist.com/rest/v2/)\n- [TypeScript](https://www.typescriptlang.org/)\n- [Zod](https://github.com/colinhacks/zod)\n",
  "bytes": 9064,
  "sha": "cb3db1cafb031c313fe1406c454035c1e256034d86fe4fa06002fcd9618e81b6",
  "repo_slug": "ecfaria/todoist-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ecfaria_todoist_mcp_850d8ddb/readme"
}