Skip to main content
Glama

Todo MCP Server

by mrgoonie
GitHub
TypeScript
1
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

TODO MCP Server

A Model Context Protocol (MCP) server for managing todo lists and items with webhook notifications, built with Bun and TypeScript.

Features

Todo List Management

  • Create new todo lists with names and descriptions
  • Read individual lists or get all lists
  • Update list names and descriptions
  • Delete lists (cascades to all items)

Todo Item Management

  • CRUD Operations: Create, read, update, delete todo items
  • Assignee Support: Assign todos to specific people
  • Priority Levels: None, low, medium, high
  • Status Tracking: pending, in_progress, completed, cancelled
  • Tags: Flexible tagging system for categorization
  • Due Dates: Set deadlines for tasks
  • Snooze Functionality: Temporarily hide items until a specific time

Advanced Features

  • Recurrence: Daily, weekly, monthly, or specific weekdays
  • Search: Find todos by title, description, or keywords
  • Filtering: Filter by assignee, tags, status, priority, due dates
  • Sorting: Sort by time, priority, creation date, or update date
  • Pagination: Limit and offset for large datasets
  • Notifications: Webhook notifications for approaching deadlines

Installation

Prerequisites

  • Bun runtime
  • SQLite3 (included with most systems)

Setup

# Clone the repository git clone <repository-url> cd mcp-todo # Install dependencies bun install # Set up environment variables cp .env.example .env # Edit .env with your configuration

Environment Variables

# webhook URL for task notifications (optional) NOTIFICATION_WEBHOOK=http://localhost:3000/api/webhooks/your-webhook-url # Database configuration DATABASE_PATH=./todo.db # Server configuration MCP_SERVER_NAME=mcp-todo MCP_SERVER_VERSION=1.0.0

Usage

Development

# Start in development mode with auto-reload bun run dev # Run type checking bun run typecheck # Run tests bun test

Production

# Start the server bun run start # Or build and run with Docker docker-compose up -d

MCP Tools

The server provides the following MCP tools:

Todo List Operations

  • createTodoList - Create a new todo list
  • getTodoList - Get a todo list by ID
  • getAllTodoLists - Get all todo lists
  • updateTodoList - Update a todo list
  • deleteTodoList - Delete a todo list

Todo Item Operations

  • createTodoItem - Create a new todo item
  • getTodoItem - Get a todo item by ID
  • searchTodoItems - Search and filter todo items
  • updateTodoItem - Update a todo item
  • markTodoDone - Mark a todo item as completed
  • deleteTodoItem - Delete a todo item

Usage Examples

Creating a Todo List
{ "name": "Work Tasks", "description": "Tasks related to work projects" }
Creating a Todo Item
{ "list_id": "list-uuid", "title": "Complete project documentation", "description": "Write comprehensive docs for the new feature", "assignee": "john.doe@example.com", "priority": "high", "tags": ["documentation", "urgent"], "due_date": "2024-12-31T23:59:59Z", "recurrence": { "type": "weekly", "weekdays": [1, 3, 5] } }
Searching Todo Items
{ "query": "documentation", "status": ["pending", "in_progress"], "priority": ["high", "medium"], "assignee": "john.doe@example.com", "due_before": "2024-12-31T23:59:59Z", "sort_field": "due_date", "sort_order": "asc", "limit": 10 }

Database Schema

The server uses SQLite with the following tables:

  • todo_lists: Stores todo list information
  • todo_items: Stores individual todo items
  • tags: Stores unique tag names
  • todo_tags: Many-to-many relationship between todos and tags
  • recurrences: Stores recurrence patterns for todos

Docker Deployment

Using Docker Compose

# Start the service docker-compose up -d # View logs docker-compose logs -f # Stop the service docker-compose down

Using Docker directly

# Build the image docker build -t mcp-todo . # Run the container docker run -d \ --name mcp-todo \ -v todo-data:/data \ -e NOTIFICATION_WEBHOOK=your-webhook-url \ mcp-todo

Notifications

When a NOTIFICATION_WEBHOOK is configured, the server will:

  1. Check for tasks with due dates within the next hour every 5 minutes
  2. Send webhook notifications for upcoming deadlines
  3. Automatically snooze notifications for 1 hour to avoid spam
  4. Include task details like title, assignee, priority, and tags

Webhook Payload Format

{ "content": "Task deadline approaching!", "data": { "id": "string"; "list_id": "string"; "title": "string"; "description": "string"; "assignee": "string"; "priority": "none"; // none, low, medium, high "status": "completed"; // pending, in_progress, completed, cancelled "tags": []; "due_date": Date; "snoozed_until": Date; "recurrence": { "type": "daily"; // daily, weekly, monthly, weekdays "weekdays": []; // 0-6 for Sunday-Saturday "day_of_month": 1; // 1-31 "next_due": Date; }; "completed_at"?: Date; "created_at": Date; "updated_at": Date; "metadata": {}; } }

API Reference

Recurrence Types

  • daily: Repeats every day
  • weekly: Repeats on specific weekdays (0=Sunday, 6=Saturday)
  • monthly: Repeats on a specific day of the month
  • weekdays: Repeats on weekdays only (Monday-Friday)

Priority Levels

  • none: No priority set
  • low: Low priority
  • medium: Medium priority
  • high: High priority

Status Options

  • pending: Task not started
  • in_progress: Task is being worked on
  • completed: Task is finished
  • cancelled: Task was cancelled

Development

Project Structure

src/ ├── db/ # Database connection and schema ├── models/ # Repository classes for data access ├── server/ # MCP server implementation ├── types/ # TypeScript type definitions └── utils/ # Utility functions

Testing

# Run all tests bun test # Run with coverage bun test --coverage # Run specific test file bun test tests/todo-list.repository.test.ts

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

License

This project is licensed under the MIT License.

Troubleshooting

Common Issues

  1. Database locked error: Ensure only one instance of the server is running
  2. Permission denied: Check file permissions for the database path
  3. Webhook not working: Verify the webhook URL is correct and accessible

Debug Mode

Set NODE_ENV=development to enable additional logging.

Support

For issues and questions, please:

  1. Check the troubleshooting section above
  2. Search existing issues on GitHub
  3. Create a new issue with detailed information

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

A Model Context Protocol server for managing todo lists and items with advanced features including task assignment, priorities, recurrence, filtering, and webhook notifications.

  1. Features
    1. Todo List Management
    2. Todo Item Management
    3. Advanced Features
  2. Installation
    1. Prerequisites
    2. Setup
    3. Environment Variables
  3. Usage
    1. Development
    2. Production
  4. MCP Tools
    1. Todo List Operations
    2. Todo Item Operations
    3. Usage Examples
  5. Database Schema
    1. Docker Deployment
      1. Using Docker Compose
      2. Using Docker directly
    2. Notifications
      1. Webhook Payload Format
    3. API Reference
      1. Recurrence Types
      2. Priority Levels
      3. Status Options
    4. Development
      1. Project Structure
      2. Testing
      3. Contributing
    5. License
      1. Troubleshooting
        1. Common Issues
        2. Debug Mode
      2. Support

        Related MCP Servers

        • Notion MCP

          Badhansen
          -
          security
          A
          license
          -
          quality
          A Model Context Protocol server that integrates with Notion's API to manage personal todo lists, allowing users to view, add, and update tasks directly from Claude.
          Last updated -
          20
          Python
          MIT License

        • Todo List MCP Server

          RegiByte
          A
          security
          A
          license
          A
          quality
          A Model Context Protocol (MCP) server that provides tools for managing todo items, including creation, updating, completion, deletion, searching, and summarizing tasks.
          Last updated -
          10
          22
          TypeScript
          MIT License

        • Task Manager MCP Server

          tradesdontlie
          -
          security
          A
          license
          -
          quality
          A Model Context Protocol server providing comprehensive task management capabilities with support for project organization, task tracking, and automatic PRD parsing into actionable items.
          Last updated -
          16
          Python
          MIT License
          • Linux
          • Apple

        • Todoist MCP Server

          stevengonsalvez
          -
          security
          A
          license
          -
          quality
          A Model Context Protocol server that enables advanced task and project management in Todoist via Claude Desktop and other MCP-compatible clients.
          Last updated -
          569
          1
          JavaScript
          MIT License

        View all related MCP servers

        New MCP Servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/mrgoonie/todo-mcp'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server