README.md•16.4 kB
# MCP Tasks 📋
[](https://cursor.com/install-mcp?name=mcp-tasks&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwbWNwLXRhc2tzJTIyJTdE)
[](https://www.npmjs.com/package/mcp-tasks)
[](https://nodejs.org/)
[](https://opensource.org/licenses/MIT)
[](https://hub.docker.com/r/flesler/mcp-tasks)
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)
## 📚 **Table of Contents**
- [✨ Features](#-features)
- [🚀 Quick Start](#-quick-start)
- [🤖 AI Integration Tips](#-ai-integration-tips)
- [🔧 Installation Examples](#-installation-examples)
- [📁 Supported File Formats](#-supported-file-formats)
- [🛠️ Available Tools](#️-available-tools)
- [🎛️ Environment Variables](#️-environment-variables)
- [📊 File Formats](#-file-formats)
- [🖥️ Server Usage](#️-server-usage)
- [💻 CLI Usage](#-cli-usage)
- [🧪 Development](#-development)
- [🛠️ Troubleshooting](#️-troubleshooting)
- [Why not let AI edit files directly?](#why-not-just-have-ai-edit-the-task-files-directly)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [🔗 Links](#-links)
## ✨ **Features**
- ⚡ **Ultra-efficient design**: Minimal tool count (5 tools) to reduce AI confusion
- 🎯 **Budget-optimized**: Batch operations, smart defaults and auto-operations minimize LLM API calls
- 🚀 **Multi-format support**: Markdown (`.md`), JSON (`.json`), and YAML (`.yml`) task files
- 🔍 **Powerful search**: Case-insensitive text/status filtering with OR logic, and ID-based lookup
- 📊 **Smart organization**: Status-based filtering with customizable workflow states
- 🎯 **Position-based indexing**: Easy task ordering with 0-based insertion
- 📁 **Multi-source support**: Manage multiple task files simultaneously
- 🔄 **Real-time updates**: Changes persist automatically to your chosen format
- 🤖 **Auto WIP management**: Automatically manages work-in-progress task limits
- 🚫 **Duplicate prevention**: Automatically prevents duplicate tasks
- 🛡️ **Type-safe**: Full TypeScript support with Zod validation
- 🔒 **Ultra-safe**: AI has no way to rewrite or delete your tasks (unless you enable it), only add and move them
- 📅 **Optional reminders**: Enable a dedicated Reminders section the AI constantly sees and can maintain
## 🚀 **Quick Start**
Add this to `~/.cursor/mcp.json` for Cursor, `~/.config/claude_desktop_config.json` for Claude Desktop.
### Option 1: NPX (Recommended)
```json
{
"mcpServers": {
"mcp-tasks": {
"command": "npx",
"args": ["-y", "mcp-tasks"]
}
}
}
```
### Option 2: Docker
```json
{
"mcpServers": {
"mcp-tasks": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"flesler/mcp-tasks"
]
}
}
}
```
## 🤖 **AI Integration Tips**
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](#-cli-usage) from a separate terminal:
```bash
npx mcp-tasks add "Your new task text" "To Do" 0
```
## 🔧 **Installation Examples**
**Full configuration with custom environment:**
```json
{
"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:
```bash
TRANSPORT=http PORT=4680 npx mcp-tasks
```
Then:
```json
{
"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.
## 🛠️ **Available Tools**
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"`).
### Tool Examples
**Setup a task file:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```json
{
"env": {
"STATUSES": "WIP,Pending,Archived,Done,To Review",
"STATUS_WIP": "WIP",
"STATUS_TODO": "Pending",
"AUTO_WIP": "false"
}
}
```
## 📊 **File Formats**
### Markdown (`.md`) - Human-Readable
```markdown
# 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
```json
{
"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
```yaml
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
```
## 🖥️ **Server Usage**
```bash
# 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
```
## 💻 **CLI Usage**
You can also use `mcp-tasks` (or `npx mcp-tasks`) as a command-line tool for quick task management:
```bash
# 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:**
- Direct access to all MCP tool functionality
- JSON output for easy parsing and scripting
- Same reliability and duplicate prevention as MCP tools
- Perfect for automation scripts and CI/CD pipelines
## 🧪 **Development**
```bash
# 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
```
## 🛠️ **Troubleshooting**
### **Requirements**
- **Node.js ≥20** - This package requires Node.js version 20 or higher
### **Common Issues**
**ERR_MODULE_NOT_FOUND when running `npx-tasks`**
- **Problem**: Error like `Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js'` when running `npx mcp-tasks`
- **Cause**: Corrupt or incomplete npx cache preventing proper dependency resolution
- **Solution**: Clear the npx cache and try again:
```bash
npx clear-npx-cache
npx mcp-tasks
```
- **Note**: This issue can occur on both Node.js v20 and v22, and the cache clear resolves it
**Where are my tasks stored?**
- Tasks are stored in the file path you specified by the AI in `tasks_setup`
- The absolute path is returned in every tool call response under `source.path`
- If you forgot the location, check any tool response or ask the AI to show it to you
**Lost content in Markdown files:**
- ⚠️ The tools will rewrite the entire file, preserving only tasks under recognized status sections
- Non-task content (notes, documentation) may be lost when tools modify the file
- Use a dedicated task file rather than mixing tasks with other content
## Why not just have AI edit the task files directly?
- **File parsing complexity:** AI must read entire files, parse markdown structure, and understand current state - expensive and error-prone
- **Multi-step operations:** Moving a task from "In Progress" to "Done" requires multiple `read_file`, `grep_search`, `sed` calls to locate and modify correct sections
- **Context loss:** Large task files forcing AI to work with incomplete chunks due to token restrictions and lose track of overall structure
- **State comprehension:** AI struggles to understand true project state when reading fragmented file sections - which tasks are actually in progress?
- **Edit precision:** Manual editing risks corrupting markdown formatting, losing tasks, or accidentally modifying the wrong sections
- **Concurrent editing conflicts:** When AI directly edits files, humans can't safely make manual changes without creating conflicts or overwrites
- **Token inefficiency:** Reading+parsing+editing cycles consume far more tokens than structured tool calls with clear inputs/outputs
- **Safety:** AI can accidentally change or delete tasks when directly editing files, but with these tools it cannot rewrite or delete your tasks
## 🤝 **Contributing**
We welcome contributions! Please:
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes with tests
4. Run: `npm run lint:full`
5. Submit a pull request
## 📄 **License**
MIT License - see [LICENSE](LICENSE) for details.
## 🔗 **Links**
- 📦 **[NPM Package](https://www.npmjs.com/package/mcp-tasks)**
- 🐙 **[GitHub Repository](https://github.com/flesler/mcp-tasks)**
- 🐛 **[Report Issues](https://github.com/flesler/mcp-tasks/issues)**
- 📚 **[MCP Specification](https://modelcontextprotocol.io/)**
- ⚡ **[FastMCP Framework](https://github.com/punkpeye/fastmcp)**