Todo MCP

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!

✨ Features

• 📝 Simple Task Management - Create, complete, and archive tasks
• 📂 Project Organization - Separate tasks by lists (perfect for different codebases/projects)
• 🎯 Priority System - Low, Medium, High, and Urgent priorities
• 🕒 Time Tracking - Automatic timestamps for creation, completion, and archiving
• 🔍 Smart Sorting - Tasks sorted by priority and age automatically
• 💾 Persistent Storage - Uses PostgreSQL for reliable data storage

🚀 Quick Start

Step 1: Install Database (Choose One)

Option A: DBngin (Recommended for Mac Users) 🍎

1. Download DBngin - A simple database manager for Mac
2. Install and open DBngin
3. Click "+" and select PostgreSQL
4. Start the PostgreSQL server
5. Create two databases:
   • todo_mcp (for your tasks)
   • todo_mcp_test (for testing)

Option B: Docker Compose (Cross-Platform) 🐳

1. Create a docker-compose.yml file:

version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: todo_mcp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

2. Run: docker-compose up -d
3. Create test database: docker exec -it <container_name> createdb -U postgres todo_mcp_test

Step 2: Configure Claude Desktop

Add this to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "todo-mcp": {
      "command": "npx",
      "args": ["-y", "@floriscornel/todo-mcp@latest"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/todo_mcp"
      }
    }
  }
}

Step 3: Start Using! 🎉

Ask Claude things like:

• "Create a new list called 'Frontend Project'"
• "Add a task to fix the login bug with high priority"
• "Show me all my urgent tasks"
• "Complete the task about updating dependencies"

💡 Real-World Examples

🔄 Code Review Workflow

You: "I'm reviewing this PR and found several issues. Can you help me track them?"

Claude: "I'll help you create tasks for the issues you found. First, let me create a list for this PR."

You: "Create a list called 'PR-123 Review Issues'"

Claude: *Creates the list*

You: "Add these tasks:
- Fix memory leak in UserService (high priority)
- Add error handling for API calls (medium)
- Update outdated dependencies (low)
- Add unit tests for new features (high)"

Claude: *Creates all tasks with appropriate priorities*

You: "Show me the high priority items first"

🐛 Bug Triage Session

You: "I just got 5 bug reports from users. Help me organize them by priority."

Claude: "Let me create a 'Bug Reports - Sprint 24' list and add these issues. What are the bugs?"

You: "Login fails on mobile Safari, checkout process crashes, slow page load, typo in footer, and dark mode toggle broken"

Claude: *Creates tasks and asks about severity*

Claude: "I've added these. The login and checkout issues sound urgent - should I mark them as high priority?"

You: "Yes, and show me all urgent tasks across all my lists so I can plan my day"

🚀 Feature Development Planning

You: "I'm starting work on a new dashboard feature. Help me break it down into tasks."

Claude: "Great! Let me create a 'Dashboard Feature' list. What components do you need to build?"

You: "I need to design the layout, create API endpoints, build the frontend components, write tests, and update documentation"

Claude: *Creates structured tasks*

Claude: "I've created tasks for each component. Should I mark the API endpoints as high priority since the frontend depends on them?"

You: "Perfect! Also add a task to review the design with the team before I start coding"

📚 Learning & Research Tracking

You: "I'm learning React Native. Can you help me track my progress?"

Claude: "I'll create a 'React Native Learning' list. What topics do you want to cover?"

You: "Navigation, state management, API integration, testing, and deployment"

Claude: *Creates learning tasks*

You: "I just finished the navigation tutorial. Mark that as complete and show me what's next"

Claude: "Great progress! Next up is state management. I can also help you find resources for that topic."

🔧 Refactoring Project

You: "I need to refactor this legacy codebase. There's so much to do, I don't know where to start."

Claude: "Let's break it down systematically. I'll create a 'Legacy Refactor' list. What are the main areas that need work?"

You: "Database queries are slow, no error handling, outdated dependencies, no tests, and the UI is a mess"

Claude: *Creates organized tasks with priorities*

Claude: "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?"

🎯 Daily Standup Preparation

You: "What did I work on yesterday and what should I focus on today?"

Claude: "Let me check your completed tasks from yesterday and show you today's priorities."

*Shows completed tasks and upcoming high-priority items*

Claude: "Yesterday you completed the user authentication fix and API documentation. Today's urgent tasks are the payment gateway integration and the mobile responsive fixes."

You: "Perfect! Add a new task to review the payment gateway with the security team before deploying"

🏃‍♂️ Sprint Planning

You: "Help me plan this 2-week sprint. I have tasks scattered across different lists."

Claude: "I'll show you all your tasks grouped by priority. Which lists should I include in the sprint planning?"

You: "Include 'Frontend Bugs', 'API Development', and 'User Stories - Q4'"

Claude: *Aggregates and prioritizes tasks*

Claude: "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?"

🔍 Code Investigation

You: "This function is behaving weirdly. Help me track what I need to investigate."

Claude: "I'll create an 'Investigation - UserAuth Bug' list. What symptoms are you seeing?"

You: "Users can't log in on weekends, but weekdays work fine. It's bizarre."

Claude: "That is strange! Let me add investigation tasks:
- Check server logs for weekend patterns
- Review cron jobs and scheduled tasks  
- Test with different user accounts
- Check database connection pooling
- Review load balancer configuration"

You: "Great breakdown! I just checked the logs - mark that complete and add a task to check if our SSL certificate renewal happens on weekends"

🎨 IDE Integration Benefits

Claude Desktop

• Persistent Context: Your tasks persist across conversations
• Natural Language: "Show me what I was working on last week"
• Smart Prioritization: Claude can help reprioritize based on deadlines

VS Code / Cursor

• Code-Aware Tasks: "Add a task to refactor this function" (while viewing code)
• Context Switching: Quickly switch between coding and task management
• Inline Planning: Plan refactoring while reviewing code

Cross-Session Continuity

• Pick Up Where You Left Off: "What was I working on before the meeting?"
• Team Handoffs: "Show the new developer what needs to be done on this feature"
• Progress Tracking: "How much of the authentication system is complete?"

📖 How It Works

Lists

Think of lists as different projects or categories:

• Frontend Repo - Tasks for your React app
• Backend API - Server-side todos
• Personal - Non-work related tasks

Tasks

Each task has:

• Name (5-120 characters) - Keep it concise and actionable
• Description (optional, up to 500 characters) - Add details if needed
• Priority - Low → Medium → High → Urgent
• Timestamps - When created, completed, or archived

Smart Organization

• Tasks are automatically sorted by priority (urgent first) and age
• Completed tasks are kept for reference but don't clutter your active list
• Archive tasks when they're no longer relevant

🛠️ Available Commands

The MCP provides these tools for Claude:

• getLists() - Show all your project lists
• createList(name, description?) - Create a new project list
• getTasks(list, includeCompleted?) - Get tasks from a specific list
• createTask(list, name, description?, priority?) - Add a new task
• completeTask(taskId) - Mark a task as done
• archiveTask(taskId) - Archive a task (removes from active view)

🔧 Configuration

Environment Variables

# Main database (required)
DATABASE_URL="postgresql://username:password@localhost:5432/todo_mcp"

# Test database (optional, for development)
TEST_DATABASE_URL="postgresql://username:password@localhost:5432/todo_mcp_test"

Database Connection Examples

# Local PostgreSQL
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/todo_mcp"

# Docker
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/todo_mcp"

# Remote database (replace with your details)
DATABASE_URL="postgresql://user:pass@your-db-host:5432/todo_mcp"

🧪 Development

Prerequisites

• Node.js 18+
• PostgreSQL 12+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/floriscornel/todo-mcp.git
cd todo-mcp

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your database URLs

# Run database migrations
npm run db:migrate

# Run tests
npm test

# Start development
npm run dev

Testing

npm test                    # Run tests once
npm run test:watch         # Run tests in watch mode  
npm run test:coverage      # Run tests with coverage report

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow the existing code style (we use Biome for formatting)
• Update documentation for user-facing changes
• Keep commits focused and descriptive

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol by Anthropic
• Uses Drizzle ORM for database operations
• Inspired by the need for better task management in AI-assisted development

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: MCP Documentation

🗺️ Roadmap

• Web interface for task management
• Task due dates and reminders
• Task dependencies and subtasks
• Export/import functionality
• Team collaboration features
• Integration with popular task managers

---

Made with ❤️ for the AI-assisted development community