Skip to main content
Glama
MCP Todo.txt Integration

MCP Todo.txt Integration

by guifelix

GitHub Actions Workflow Status NPM Downloads GitHub Downloads (all assets, all releases) NPM Version License Types Last Commit GitHub issues GitHub starts


MCP Todo.txt Integration

Overview

The MCP Todo.txt Integration is a server implementation of the Model Context Protocol (MCP) that enables interaction with Todo.txt files. This project allows LLMs to manage tasks in a Todo.txt file programmatically using the MCP protocol.

Related MCP server: Todoist MCP Server

Features

Core Features

  • Resources

    • Expose the list of tasks as a resource.

    • Filter tasks by context, project, or priority.

  • Tools

    1. Add Task: Add a new task with optional metadata.

    2. Mark Task as Completed: Mark a task as completed.

    3. Delete Task: Remove a task.

    4. List Tasks: Retrieve all tasks with filtering options.

    5. Search Tasks: Search for tasks based on keywords or metadata.

    6. Sort Tasks: Sort tasks by priority, creation date, or completion date.

    7. Filter Tasks: Filter tasks by specific criteria.

    8. Add Metadata: Add custom metadata to tasks.

    9. Remove Metadata: Remove specific metadata from tasks.

    10. Batch Operations: Perform batch updates or deletions.

  • Prompts

    • Summarize tasks.

    • Generate a new task description.

Advanced Features

  • Dynamic Task Management: Update tasks dynamically based on input or triggers.

  • Session Management: Manage tasks across multiple requests.

Installation

For quick installation, use the one-click installation button below

Install with NPX in VS Code

  1. Clone the repository:

    git clone <repository-url>
    cd todomcp
  2. Install dependencies:

    npm install
  3. Build the project:

    npm run build

Usage

  1. Start the MCP server:

    npm start
  2. Interact with the server using MCP-compliant clients or tools.

Configuration

  • The path to the Todo.txt file can be configured using the TODO_FILE_PATH environment variable. If not set, the default path is todo.txt in the project root.

Development

  • To run the project in development mode:

    npm run dev
  • To run tests:

    npm test

Dependencies

  • @modelcontextprotocol/sdk

  • jsTodoTxt

  • zod

Documentation

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

License

This project is licensed under the MIT License.

Available Tools

11 tools
add-metadataB

Add custom metadata (key-value pairs) to a task by ID.

Inputs: taskId (required), metadata (required).

add-taskB

Add a new task to the todo list. Description must be plain text. Priority must be a single uppercase letter (A-Z). Contexts must start with @, projects with +.

Inputs: description (required), priority, contexts, projects, +1 more.

batch-operationsB

Perform batch operations (update, delete, mark-complete) on tasks matching criteria.

Inputs: operations (required).

complete-taskB

Mark a task as completed by its 1-based ID.

Inputs: taskId (required).

delete-taskB

Delete a task by its 1-based ID.

Inputs: taskId (required).

filter-tasksC

Filter tasks by specific criteria (priority, context, project).

Inputs: criteria (required).

list-tasksC

List all tasks, optionally filtered by priority, context, project, or metadata.

Inputs: filter.

remove-metadataC

Remove specific metadata keys from a task by ID.

Inputs: taskId (required), keys (required).

search-tasksB

Search for tasks containing a query string.

Inputs: query (required).

sort-tasksC

Sort tasks by priority, creation date, or completion date.

Inputs: by (required).

update-taskC

Update a task's fields (description, priority, contexts, projects, metadata) by ID.

Inputs: taskId (required), updates (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes (add, update, delete, complete, list, search, sort, filter, metadata operations). However, filter-tasks and list-tasks overlap somewhat since list-tasks already supports filtering by priority, context, project, or metadata, which could cause an agent to pick the wrong one.

    Naming Consistency4/5

    Tool names consistently use a verb-noun pattern (add-task, update-task, delete-task, list-tasks, search-tasks, sort-tasks, complete-task). Minor deviations: batch-operations is a noun phrase rather than verb-noun, and filter-tasks overlaps with list-tasks' filtering capability.

    Tool Count4/5

    11 tools is a reasonable count for a todo.txt server covering task CRUD, metadata, search, sorting, filtering, and batch operations. It is slightly on the higher side but each tool addresses a distinct operation, so the count feels appropriate.

    Completeness4/5

    The tool set covers the core todo.txt lifecycle well: add, list, update, complete, delete, search, sort, filter, and metadata management. Minor gaps include no explicit undo/reopen-completed-task operation and no way to move tasks between lists, but these are not critical for a todo.txt integration.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers