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)
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
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:
{
"mcpServers": {
"mcp-tasks": {
"command": "npx",
"args": ["-y", "mcp-tasks"],
"env": {
"TRANSPORT": "http",
"PORT": "4680"
}
}
}
}
| 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_:
| Tool | Description | Parameters |
|---|---|---|
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}]}
| 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 |
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"
}
}
.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) - 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!"
]
}
}
.yml) - Configuration-Friendlygroups:
"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.
FAQs
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)
The npm package mcp-tasks receives a total of 42 weekly downloads. As such, mcp-tasks popularity was classified as not popular.
We found that mcp-tasks demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.