Tasks
STDIOEfficient task manager with multi-format support and budget-optimized AI integration capabilities
Efficient task manager with multi-format support and budget-optimized AI integration capabilities
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:
First run the server:
TRANSPORT=http PORT=4680 npx mcp-tasks
Then:
{ "mcpServers": { "mcp-tasks": { "type": "streamableHttp", "url": "http://localhost:4680/mcp" } } }
| 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.