Skip to main content
Glama

Agent TODO MCP Server

Now all editors have this feature so yep...

A Model Context Protocol server for AI agents to manage tasks and track progress across projects.

Features

  • Create, update, and manage TODOs with detailed metadata

  • Track progress, status, priority, and dependencies

  • Explicit project isolation to prevent data mixup between workspaces

  • Search, filter, and generate comprehensive reports

  • Persistent JSON storage with complete project separation

Related MCP server: Tiny TODO MCP

Installation

npm install -g agent-todo-mcp

From Source

git clone https://github.com/w04m1/agent-todo-mcp.git
cd agent-todo-mcp
npm install
npm run build
npm install -g .

Configuration

Add to your Claude Desktop/Cursor/VSCode/etc. config:

{
  "mcpServers": {
    "agent-todo": {
      "command": "agent-todo-mcp"
    }
  }
}

How AI Models Use This Server

When AI models interact with this MCP server, they follow this workflow:

  1. Check existing projects with list_projects

  2. Create or switch to a project with switch_project

  3. Create and manage TODOs within that project workspace

Project Management

Project Naming Best Practices

When creating projects, use descriptive names that clearly identify the workspace:

  • ✅ "my-react-app" - Good descriptive name

  • ✅ "backend-api-v2" - Clear project identifier

  • ✅ "research-ml-models" - Descriptive and specific

  • ❌ "project1" - Too generic

  • ❌ "temp" - Not descriptive

Project Isolation & Storage

Each project workspace is completely isolated. TODOs are stored in:

~/.agent-todos/
├── my-react-app/todos.json      # Project: "my-react-app"
├── backend-api-v2/todos.json    # Project: "backend-api-v2"
├── research-ml-models/todos.json # Project: "research-ml-models"
└── default-workspace/todos.json # Default fallback project

Architecture

  • Complete Isolation: Each project has its own TODO storage

  • Explicit Management: Projects are created explicitly via switch_project tool

  • Persistent Storage: All data persists in ~/.agent-todos/{projectId}/

  • ⚠️ No Deletion: Projects cannot be deleted through the API (only individual TODOs can be deleted)

Available Tools

Project Management

  • list_projects - List all available project workspaces

  • switch_project - Create new project or switch between existing ones

  • get_project_info - Show current project details

Core Management

  • create_todo - Create new tasks

  • update_todo - Update existing tasks

  • delete_todo - Remove tasks

  • list_todos - List and filter tasks

  • get_todo - Get detailed task info

Search & Analytics

  • search_todos - Search across all tasks

  • generate_report - Create progress reports

  • get_stats - Quick statistics

TODO Structure

interface Todo {
  id: string;
  title: string;
  description?: string;
  status: "pending" | "in-progress" | "completed" | "blocked";
  priority: "low" | "medium" | "high" | "urgent";
  progress: number; // 0-100
  tags: string[];
  dependencies: string[]; // Other TODO IDs
  dueDate?: string;
  metadata: Record<string, any>;
  createdAt: string;
  updatedAt: string;
}

Development

npm run dev    # Development mode
npm run build  # Build project
npm start      # Run built server

License

MIT


Built with AI for AI 🤡

Available Tools

11 tools
create_todoA

Create a new TODO item with optional metadata. IMPORTANT: Before creating your first TODO, call list_projects to check existing workspaces, then call switch_project to set up your project workspace.

Inputs: title (required), tags, dueDate, metadata, +3 more.

delete_todoA

Delete a TODO item

Inputs: id (required), force.

generate_reportC

Generate a comprehensive progress report

Inputs: groupBy, timeframe, includeCompleted.

get_project_infoB

Get current project workspace information

Inputs: no named parameters.

get_statsB

Get quick statistics about TODOs

Inputs: no named parameters.

get_todoA

Get detailed information about a specific TODO

Inputs: id (required).

list_projectsA

List all available project workspaces. RECOMMENDED: Call this first to see existing projects before creating new ones with switch_project.

Inputs: no named parameters.

list_todosB

List TODOs with optional filtering and sorting

Inputs: tag, limit, sortBy, status, +2 more.

search_todosA

Search TODOs by title, description, or metadata

Inputs: query (required), caseSensitive.

switch_projectA

Switch to a different project workspace or create a new one. IMPORTANT: You must call this tool to set up a project before creating any TODOs. Recommendation: Call list_projects first to see existing workspaces and avoid creating duplicates. Each project isolates its TODO data completely.

Inputs: projectId (required).

update_todoB

Update an existing TODO item

Inputs: id (required), tags, title, status, +10 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes: CRUD operations for TODOs are separate (create, list, get, update, delete, search). Potential overlap exists between generate_report and get_stats, as both provide aggregate views, but report is more comprehensive while stats are quick numbers, so they are distinguishable.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_todo, list_projects, get_stats). There are no mixed conventions or vague verbs, making the naming predictable and easy to navigate.

    Tool Count5/5

    With 11 tools, the count is well-scoped for a TODO management server with project workspace support. Each tool serves a distinct need, and the number is neither too sparse nor overwhelming for the apparent functionality.

    Completeness4/5

    The TODO lifecycle is fully covered with create, read, update, delete, list, and search operations. Project management is sufficient with list, switch/get info, though there is no explicit delete or rename project tool, which is a minor gap but not critical for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers