Todos

You are about to use a local, MCP-compliant todo list application that can be controlled by AI assistants. It stores your tasks on your device, supports full CRUD operations, and exposes MCP endpoints so chatbots and models can manage your tasks via natural language or structured requests.

How to use

You can interact with this MCP server through an MCP client to manage your tasks. Use natural language prompts or explicit commands to create, read, update, or delete todos. The available endpoints expose common task operations such as listing all tasks, filtering by status, adding new tasks, marking items as done, and updating details like descriptions or due dates. For example, you can ask your AI assistant to show all pending tasks, add a new reminder, or mark a specific task as complete. The server is designed to work offline on your machine and does not require any external accounts.

How to install

# Prerequisites
- Node.js v16 or higher
- npm or yarn

# Installation steps
# 1) Clone the project
git clone https://github.com/tomelliot/todos-mcp.git
dcd mcp-todo-app

# 2) Install dependencies
npm install
# or
yarn install

# 3) Start the development server
npm run dev
# or
yarn dev

Configuration and MCP setup

To enable MCP control from an assistant, add the MCP server configuration to your Claude (or compatible MCP client) setup. The configuration defines the local server that the assistant can talk to in order to manage your todos.

{
  "mcpServers": {
    // ... other servers ...
    "todos": {
      "command": "npx",
      "args": ["-y", "todos-mcp"]
    }
    // ... other servers ...
  }
}

Notes on usage and tools

This MCP server exposes a set of tools that let you manage todos programmatically. You can retrieve a specific item by ID, list all items or filter by status, add new items, update descriptions or due dates, and mark tasks as completed. Use the MCP client to call these tools in natural language or through explicit tool invocations.

Available tools

Get-Todo

Retrieve a specific todo item by its ID, returning its description, status, and due date.

List-All-Todos

Return all todos in the system, with optional sorting or paging if supported by the client.

List-Completed-Todos

List all tasks that have been marked as completed.

List-Pending-Todos

List all tasks that are not yet completed, i.e., pending items.

Add-Todo

Create a new todo with a description and optional due date.

Mark-Todo-Done

Mark a specific todo item as completed.

List-Due-Today

List pending todos that are due today or are overdue.

List-Due-This-Week

List pending todos due this week or earlier.

Update-Todo

Update a todo's description and/or due date.