agent-todo-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-todo-mcp list all todos in my-react-app project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Via npm (Recommended)
npm install -g agent-todo-mcpFrom 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:
Check existing projects with
list_projectsCreate or switch to a project with
switch_projectCreate 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 projectArchitecture
Complete Isolation: Each project has its own TODO storage
Explicit Management: Projects are created explicitly via
switch_projecttoolPersistent 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 workspacesswitch_project- Create new project or switch between existing onesget_project_info- Show current project details
Core Management
create_todo- Create new tasksupdate_todo- Update existing tasksdelete_todo- Remove taskslist_todos- List and filter tasksget_todo- Get detailed task info
Search & Analytics
search_todos- Search across all tasksgenerate_report- Create progress reportsget_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 serverLicense
MIT
Built with AI for AI 🤡
Available Tools
11 toolscreate_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for building and testing AI agents with multi-model experimentation and insights.
Project management shared by people and AI agents, with persistent project state through MCP.
Project tracker for AI agents and teams: file, claim, update and hand off tickets over MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA server implementation of the Model Context Protocol (MCP) for managing development workflow with features like project management, task tracking, and QA review support.3AGPL 3.0
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.5-
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server providing comprehensive task management capabilities with support for project organization, task tracking, and automatic PRD parsing into actionable items.38MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.2924 npm88MIT