An efficient task manager. Designed to minimize tool confusion and maximize LLM budget efficiency while providing powerful search, filtering, and organization capabilities across multiple file formats (Markdown, JSON, YAML)
.md), JSON (.json), and YAML (.yml) task filesAdd this to ~/.cursor/mcp.json for Cursor, ~/.config/claude_desktop_config.json for Claude Desktop.
{
"mcpServers": {
"mcp-tasks": {
"command": "npx",
"args": ["-y", "mcp-tasks"]
}
}
}
{
"mcpServers": {
"mcp-tasks": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"flesler/mcp-tasks"
]
}
}
}
To encourage the AI to use these tools, you can start with a prompt like the following, with any path you want with .md (recommended), .json, .yml:
Use mcp-tasks tools to track our work in path/to/tasks.md
If you are telling it about new or updated tasks, you can append this to the end of your prompt:
use mcp-tasks
Adding tasks while AI works: To safely add tasks without interfering with AI operations, use the CLI from a separate terminal:
npx mcp-tasks add "Your new task text" "To Do" 0ð§ Installation Examples
Full configuration with custom environment:
{
"mcpServers": {
"mcp-tasks": {
"command": "npx",
"args": ["-y", "mcp-tasks"],
"env": {
"STATUS_WIP": "In Progress",
"STATUS_TODO": "To Do",
"STATUS_DONE": "Done",
"STATUS_REMINDERS": "Reminders",
"STATUS_NOTES": "Notes",
"STATUSES": "In Progress,To Do,Done,Backlog,Reminders,Notes",
"AUTO_WIP": "true",
"PREFIX_TOOLS": "true",
"KEEP_DELETED": "true",
"TRANSPORT": "stdio",
"PORT": "4680",
"INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks"
}
}
}
}
HTTP transport for remote access:
First run the server:
TRANSPORT=http PORT=4680 npx mcp-tasks
Then:
{
"mcpServers": {
"mcp-tasks": {
"type": "streamableHttp",
"url": "http://localhost:4680/mcp"
}
}
} ð Supported File Formats Extension Format Best For Auto-Created .md Markdown Human-readable task lists â
.json JSON Structured data, APIs â
.yml YAML Configuration files â
Format is auto-detected from file extension. All formats support the same features and can be mixed in the same project.
Recommended: Markdown (.md) for human readability and editing
â ï¸ Warning: Start with a new file rather than using pre-existing task files to avoid losing non-task content.
When PREFIX_TOOLS=true (default), all tools are prefixed with tasks_:
tasks_setup Initialize a task file (creates if missing, supports .md, .json, .yml) source_path, workspace? tasks_search Search tasks with filtering source_id, statuses?, terms?, ids? tasks_add Add new tasks to a status source_id, texts[], status, index? tasks_update Update tasks by ID source_id, ids[], status, index? tasks_summary Get task counts and work-in-progress source_id
ID Format: Both source_id (from file path) and task id (from task text) are 4-character alphanumeric strings (e.g., "xK8p", "m3Qw").
Setup a task file:
tasks_setup({
workspace: "/path/to/project",
source_path: "tasks.md" // relative to workspace or absolute
// source_path: "tasks.json"
// source_path: "tasks.yml"
})
// Returns: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}
// Source ID (4-char alphanumeric) is used for all subsequent operations
Add tasks:
tasks_add({
source_id: "xK8p", // From setup response
texts: ["Implement authentication", "Write tests"],
status: "To Do",
index: 0 // Add at top (optional)
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":2,"In Progress":0,"Done":0,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0},{"id":"p9Lx","text":"Write tests","status":"To Do","index":1}]}
Search and filter:
tasks_search({
source_id: "xK8p", // From setup response
terms: ["auth", "deploy"], // Search terms (text or status, OR logic)
statuses: ["To Do"], // Filter by status
ids: ["m3Qw", "p9Lx"] // Filter by specific task IDs
})
// Returns: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]
Update tasks status:
tasks_update({
source_id: "xK8p", // From setup response
ids: ["m3Qw", "p9Lx"], // Task IDs from add/search responses
status: "Done" // Use "Deleted" to remove
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":2,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"Done","index":0},{"id":"p9Lx","text":"Write tests","status":"Done","index":1}]}
Get overview:
tasks_summary({
source_id: "xK8p" // From setup response
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":1,"Done":2,"inProgress":[{"id":"r7Km","text":"Fix critical bug","status":"In Progress","index":0}]} ðï¸ Environment Variables Variable Default Description TRANSPORT stdio Transport mode: stdio or http PORT 4680 HTTP server port (when TRANSPORT=http) PREFIX_TOOLS true Prefix tool names with tasks_ STATUS_WIP In Progress Work-in-progress status name STATUS_TODO To Do ToDo status name STATUS_DONE Done Completed status name STATUS_REMINDERS Reminders Reminders for the AI (empty string to disable) STATUS_NOTES Notes Notes/non-actionable tasks (empty string to disable) STATUSES Backlog Comma-separated additional statuses AUTO_WIP true One WIP moves rest to To Do, first To Do to WIP when no WIP's KEEP_DELETED true Retain deleted tasks (AI can't lose you tasks!) INSTRUCTIONS ... Included in all tool responses, for the AI to follow SOURCES_PATH ./sources.json File to store source registry (internal) DEBUG false if true, enable the tasks_debug tool Advanced Configuration Examples
Optional, the WIP/ToDo/Done statuses can be included to control their order.
Custom workflow statuses:
{
"env": {
"STATUSES": "WIP,Pending,Archived,Done,To Review",
"STATUS_WIP": "WIP",
"STATUS_TODO": "Pending",
"AUTO_WIP": "false"
}
} Markdown (.md) - Human-Readable
# Tasks - File Name ## In Progress - [ ] Write user registration ## To Do - [ ] Implement authentication - [ ] Set up CI/CD pipeline ## Backlog - [ ] Plan architecture - [ ] Design database schema ## Done - [x] Set up project structure - [x] Initialize repository ## Reminders - [ ] Don't move to Done until you verified it works - [ ] After you move to Done, commit all the changes, use the task name as the commit message ## Notes - [ ] The task tools were really great to use!JSON (
.json) - Structured Data
{
"groups": {
"In Progress": [
"Write user registration"
],
"To Do": [
"Implement authentication",
"Set up CI/CD pipeline"
],
"Backlog": [
"Plan architecture",
"Design database schema"
],
"Done": [
"Set up project structure",
"Initialize repository"
],
"Reminders": [
"Don't move to Done until you verified it works",
"After you move to Done, commit all the changes, use the task name as the commit message"
],
"Notes": [
"The task tools were really great to use!"
]
}
} YAML (.yml) - Configuration-Friendly
groups:
"In Progress":
- Write user registration
"To Do":
- Implement authentication
- Set up CI/CD pipeline
Backlog:
- Plan architecture
- Design database schema
Done:
- Set up project structure
- Initialize repository
Reminders:
- Don't move to Done until you verified it works
- After you move to Done, commit all the changes, use the task name as the commit message
# Show help mcp-tasks --help # Default: stdio transport mcp-tasks # HTTP transport TRANSPORT=http mcp-tasks TRANSPORT=http PORT=8080 mcp-tasks # Custom configuration STATUS_WIP="Working" AUTO_WIP=false mcp-tasks
You can also use mcp-tasks (or npx mcp-tasks) as a command-line tool for quick task management:
# Setup a task file mcp-tasks setup tasks.md $PWD # Setup with workspace # Add tasks mcp-tasks add "Implement authentication" # Defaults to "To Do" status mcp-tasks add "Write tests" "Backlog" # Add with specific status mcp-tasks add "Fix critical bug" "In Progress" 0 # Add at top (index 0) # Search tasks mcp-tasks search # All tasks mcp-tasks search "" "auth,login" # Search for specific terms mcp-tasks search "To Do,Done" "" # Filter by statuses mcp-tasks search "In Progress" "bug" # Filter by status and search terms # Update task status (comma-separated IDs) mcp-tasks update m3Qw,p9Lx Done # Get summary mcp-tasks summary # Add a reminder (feature must be enabled with REMINDERS=true) mcp-tasks add "Don't move to Done until you verified it works" Reminders
CLI Features:
# Clone and setup git clone https://github.com/flesler/mcp-tasks cd mcp-tasks npm install # Development mode (auto-restart) npm run dev # STDIO transport npm run dev:http # HTTP transport on port 4680 # Build and test npm run build # Compile TypeScript npm run lint # Check code style npm run lint:full # Build + lint
ERR_MODULE_NOT_FOUND when running npx-tasks
Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js' when running npx mcp-tasksnpx clear-npx-cache npx mcp-tasks
Where are my tasks stored?
tasks_setupsource.pathLost content in Markdown files:
read_file, grep_search, sed calls to locate and modify correct sectionsWe welcome contributions! Please:
git checkout -b feature-namenpm run lint:fullMIT License - see LICENSE for details.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4