{"id":46146188,"url":"https://github.com/floriscornel/todo-mcp","last_synced_at":"2026-03-02T07:21:18.940Z","repository":{"id":298923746,"uuid":"1001523100","full_name":"floriscornel/todo-mcp","owner":"floriscornel","description":"A simple, powerful Todo list manager for Claude Desktop and other MCP-compatible AI assistants. Organize your tasks across different projects with priorities and never lose track of what needs to be done!","archived":false,"fork":false,"pushed_at":"2025-09-09T20:58:23.000Z","size":202,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-18T17:27:00.503Z","etag":null,"topics":["mcp","mcp-server","model-context-protocol","model-context-protocol-server","todo","todolist"],"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/floriscornel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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}},"created_at":"2025-06-13T14:24:14.000Z","updated_at":"2025-07-08T15:40:38.000Z","dependencies_parsed_at":"2025-06-13T16:57:29.029Z","dependency_job_id":"d124693c-4b02-4f5e-9b56-74012584d3ab","html_url":"https://github.com/floriscornel/todo-mcp","commit_stats":null,"previous_names":["floriscornel/todo-mcp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/floriscornel/todo-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floriscornel%2Ftodo-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floriscornel%2Ftodo-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floriscornel%2Ftodo-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floriscornel%2Ftodo-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/floriscornel","download_url":"https://codeload.github.com/floriscornel/todo-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floriscornel%2Ftodo-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29994873,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["mcp","mcp-server","model-context-protocol","model-context-protocol-server","todo","todolist"],"created_at":"2026-03-02T07:21:18.225Z","updated_at":"2026-03-02T07:21:18.914Z","avatar_url":"https://github.com/floriscornel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Todo MCP\n\n[![npm version](https://img.shields.io/npm/v/@floriscornel/todo-mcp.svg)](https://www.npmjs.com/package/@floriscornel/todo-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@floriscornel/todo-mcp.svg)](https://www.npmjs.com/package/@floriscornel/todo-mcp)\n[![codecov](https://codecov.io/gh/floriscornel/todo-mcp/graph/badge.svg)](https://app.codecov.io/gh/floriscornel/todo-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/floriscornel/todo-mcp.svg)](https://github.com/floriscornel/todo-mcp/stargazers)\n\nA simple, powerful Todo list manager for Claude Desktop and other MCP-compatible AI assistants. Organize your tasks across different projects with priorities and never lose track of what needs to be done!\n\n## ✨ Features\n\n- 📝 **Simple Task Management** - Create, complete, and archive tasks\n- 📂 **Project Organization** - Separate tasks by lists (perfect for different codebases/projects)\n- 🎯 **Priority System** - Low, Medium, High, and Urgent priorities\n- 🕒 **Time Tracking** - Automatic timestamps for creation, completion, and archiving\n- 🔍 **Smart Sorting** - Tasks sorted by priority and age automatically\n- 💾 **Persistent Storage** - Uses PostgreSQL for reliable data storage\n\n## 🚀 Quick Start\n\n### Step 1: Install Database (Choose One)\n\n#### Option A: DBngin (Recommended for Mac Users) 🍎\n1. Download [DBngin](https://dbngin.com/) - A simple database manager for Mac\n2. Install and open DBngin\n3. Click \"+\" and select PostgreSQL\n4. Start the PostgreSQL server\n5. Create two databases:\n   - `todo_mcp` (for your tasks)\n   - `todo_mcp_test` (for testing)\n\n#### Option B: Docker Compose (Cross-Platform) 🐳\n1. Create a `docker-compose.yml` file:\n```yaml\nversion: '3.8'\nservices:\n  postgres:\n    image: postgres:15\n    environment:\n      POSTGRES_USER: postgres\n      POSTGRES_PASSWORD: postgres\n      POSTGRES_DB: todo_mcp\n    ports:\n      - \"5432:5432\"\n    volumes:\n      - postgres_data:/var/lib/postgresql/data\n\nvolumes:\n  postgres_data:\n```\n\n2. Run: `docker-compose up -d`\n3. Create test database: `docker exec -it \u003ccontainer_name\u003e createdb -U postgres todo_mcp_test`\n\n### Step 2: Configure Claude Desktop\n\nAdd this to your Claude Desktop MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"todo-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@floriscornel/todo-mcp@latest\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgresql://postgres:postgres@localhost:5432/todo_mcp\"\n      }\n    }\n  }\n}\n```\n\n### Step 3: Start Using! 🎉\n\nAsk Claude things like:\n- \"Create a new list called 'Frontend Project'\"\n- \"Add a task to fix the login bug with high priority\"\n- \"Show me all my urgent tasks\"\n- \"Complete the task about updating dependencies\"\n\n## 💡 Real-World Examples\n\n### 🔄 **Code Review Workflow**\n```\nYou: \"I'm reviewing this PR and found several issues. Can you help me track them?\"\n\nClaude: \"I'll help you create tasks for the issues you found. First, let me create a list for this PR.\"\n\nYou: \"Create a list called 'PR-123 Review Issues'\"\n\nClaude: *Creates the list*\n\nYou: \"Add these tasks:\n- Fix memory leak in UserService (high priority)\n- Add error handling for API calls (medium)\n- Update outdated dependencies (low)\n- Add unit tests for new features (high)\"\n\nClaude: *Creates all tasks with appropriate priorities*\n\nYou: \"Show me the high priority items first\"\n```\n\n### 🐛 **Bug Triage Session**\n```\nYou: \"I just got 5 bug reports from users. Help me organize them by priority.\"\n\nClaude: \"Let me create a 'Bug Reports - Sprint 24' list and add these issues. What are the bugs?\"\n\nYou: \"Login fails on mobile Safari, checkout process crashes, slow page load, typo in footer, and dark mode toggle broken\"\n\nClaude: *Creates tasks and asks about severity*\n\nClaude: \"I've added these. The login and checkout issues sound urgent - should I mark them as high priority?\"\n\nYou: \"Yes, and show me all urgent tasks across all my lists so I can plan my day\"\n```\n\n### 🚀 **Feature Development Planning**\n```\nYou: \"I'm starting work on a new dashboard feature. Help me break it down into tasks.\"\n\nClaude: \"Great! Let me create a 'Dashboard Feature' list. What components do you need to build?\"\n\nYou: \"I need to design the layout, create API endpoints, build the frontend components, write tests, and update documentation\"\n\nClaude: *Creates structured tasks*\n\nClaude: \"I've created tasks for each component. Should I mark the API endpoints as high priority since the frontend depends on them?\"\n\nYou: \"Perfect! Also add a task to review the design with the team before I start coding\"\n```\n\n### 📚 **Learning \u0026 Research Tracking**\n```\nYou: \"I'm learning React Native. Can you help me track my progress?\"\n\nClaude: \"I'll create a 'React Native Learning' list. What topics do you want to cover?\"\n\nYou: \"Navigation, state management, API integration, testing, and deployment\"\n\nClaude: *Creates learning tasks*\n\nYou: \"I just finished the navigation tutorial. Mark that as complete and show me what's next\"\n\nClaude: \"Great progress! Next up is state management. I can also help you find resources for that topic.\"\n```\n\n### 🔧 **Refactoring Project**\n```\nYou: \"I need to refactor this legacy codebase. There's so much to do, I don't know where to start.\"\n\nClaude: \"Let's break it down systematically. I'll create a 'Legacy Refactor' list. What are the main areas that need work?\"\n\nYou: \"Database queries are slow, no error handling, outdated dependencies, no tests, and the UI is a mess\"\n\nClaude: *Creates organized tasks with priorities*\n\nClaude: \"I've prioritized database performance and error handling as urgent since they affect users directly. Want me to help you tackle the database issues first?\"\n```\n\n### 🎯 **Daily Standup Preparation**\n```\nYou: \"What did I work on yesterday and what should I focus on today?\"\n\nClaude: \"Let me check your completed tasks from yesterday and show you today's priorities.\"\n\n*Shows completed tasks and upcoming high-priority items*\n\nClaude: \"Yesterday you completed the user authentication fix and API documentation. Today's urgent tasks are the payment gateway integration and the mobile responsive fixes.\"\n\nYou: \"Perfect! Add a new task to review the payment gateway with the security team before deploying\"\n```\n\n### 🏃‍♂️ **Sprint Planning**\n```\nYou: \"Help me plan this 2-week sprint. I have tasks scattered across different lists.\"\n\nClaude: \"I'll show you all your tasks grouped by priority. Which lists should I include in the sprint planning?\"\n\nYou: \"Include 'Frontend Bugs', 'API Development', and 'User Stories - Q4'\"\n\nClaude: *Aggregates and prioritizes tasks*\n\nClaude: \"Here are your urgent and high-priority tasks. Based on your usual velocity, I'd recommend focusing on these 8 tasks for the sprint. Should I create a 'Sprint 12' list to track them?\"\n```\n\n### 🔍 **Code Investigation**\n```\nYou: \"This function is behaving weirdly. Help me track what I need to investigate.\"\n\nClaude: \"I'll create an 'Investigation - UserAuth Bug' list. What symptoms are you seeing?\"\n\nYou: \"Users can't log in on weekends, but weekdays work fine. It's bizarre.\"\n\nClaude: \"That is strange! Let me add investigation tasks:\n- Check server logs for weekend patterns\n- Review cron jobs and scheduled tasks  \n- Test with different user accounts\n- Check database connection pooling\n- Review load balancer configuration\"\n\nYou: \"Great breakdown! I just checked the logs - mark that complete and add a task to check if our SSL certificate renewal happens on weekends\"\n```\n\n## 🎨 **IDE Integration Benefits**\n\n### **Claude Desktop**\n- **Persistent Context**: Your tasks persist across conversations\n- **Natural Language**: \"Show me what I was working on last week\"\n- **Smart Prioritization**: Claude can help reprioritize based on deadlines\n\n### **VS Code / Cursor**\n- **Code-Aware Tasks**: \"Add a task to refactor this function\" (while viewing code)\n- **Context Switching**: Quickly switch between coding and task management\n- **Inline Planning**: Plan refactoring while reviewing code\n\n### **Cross-Session Continuity**\n- **Pick Up Where You Left Off**: \"What was I working on before the meeting?\"\n- **Team Handoffs**: \"Show the new developer what needs to be done on this feature\"\n- **Progress Tracking**: \"How much of the authentication system is complete?\"\n\n## 📖 How It Works\n\n### Lists\nThink of lists as different projects or categories:\n- **Frontend Repo** - Tasks for your React app\n- **Backend API** - Server-side todos\n- **Personal** - Non-work related tasks\n\n### Tasks\nEach task has:\n- **Name** (5-120 characters) - Keep it concise and actionable\n- **Description** (optional, up to 500 characters) - Add details if needed\n- **Priority** - Low → Medium → High → Urgent\n- **Timestamps** - When created, completed, or archived\n\n### Smart Organization\n- Tasks are automatically sorted by priority (urgent first) and age\n- Completed tasks are kept for reference but don't clutter your active list\n- Archive tasks when they're no longer relevant\n\n## 🛠️ Available Commands\n\nThe MCP provides these tools for Claude:\n\n- `getLists()` - Show all your project lists\n- `createList(name, description?)` - Create a new project list\n- `getTasks(list, includeCompleted?)` - Get tasks from a specific list\n- `createTask(list, name, description?, priority?)` - Add a new task\n- `completeTask(taskId)` - Mark a task as done\n- `archiveTask(taskId)` - Archive a task (removes from active view)\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\n# Main database (required)\nDATABASE_URL=\"postgresql://username:password@localhost:5432/todo_mcp\"\n\n# Test database (optional, for development)\nTEST_DATABASE_URL=\"postgresql://username:password@localhost:5432/todo_mcp_test\"\n```\n\n### Database Connection Examples\n\n```bash\n# Local PostgreSQL\nDATABASE_URL=\"postgresql://postgres:postgres@localhost:5432/todo_mcp\"\n\n# Docker\nDATABASE_URL=\"postgresql://postgres:postgres@localhost:5432/todo_mcp\"\n\n# Remote database (replace with your details)\nDATABASE_URL=\"postgresql://user:pass@your-db-host:5432/todo_mcp\"\n```\n\n## 🧪 Development\n\n### Prerequisites\n- Node.js 18+ \n- PostgreSQL 12+\n- npm or yarn\n\n### Setup\n```bash\n# Clone the repository\ngit clone https://github.com/floriscornel/todo-mcp.git\ncd todo-mcp\n\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your database URLs\n\n# Run database migrations\nnpm run db:migrate\n\n# Run tests\nnpm test\n\n# Start development\nnpm run dev\n```\n\n### Testing\n```bash\nnpm test                    # Run tests once\nnpm run test:watch         # Run tests in watch mode  \nnpm run test:coverage      # Run tests with coverage report\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** and add tests\n4. **Run the test suite**: `npm test`\n5. **Commit your changes**: `git commit -m 'Add amazing feature'`\n6. **Push to the branch**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### Development Guidelines\n- Write tests for new features\n- Follow the existing code style (we use Biome for formatting)\n- Update documentation for user-facing changes\n- Keep commits focused and descriptive\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic\n- Uses [Drizzle ORM](https://orm.drizzle.team/) for database operations\n- Inspired by the need for better task management in AI-assisted development\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/floriscornel/todo-mcp/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/floriscornel/todo-mcp/discussions)\n- **Documentation**: [MCP Documentation](https://modelcontextprotocol.io/)\n\n## 🗺️ Roadmap\n\n- [ ] Web interface for task management\n- [ ] Task due dates and reminders\n- [ ] Task dependencies and subtasks\n- [ ] Export/import functionality\n- [ ] Team collaboration features\n- [ ] Integration with popular task managers\n\n---\n\n**Made with ❤️ for the AI-assisted development community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloriscornel%2Ftodo-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloriscornel%2Ftodo-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloriscornel%2Ftodo-mcp/lists"}