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
- 🚀 Quick Start
- 🤖 AI Integration Tips
- 🔧 Installation Examples
- 📁 Supported File Formats
- 🛠️ Available Tools
- 🎛️ Environment Variables
- 📊 File Formats
- 🖥️ Server Usage
- 💻 CLI Usage
- 🧪 Development
- 🛠️ Troubleshooting
- Why not let AI edit files directly?
- 🤝 Contributing
- 📄 License
- 🔗 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)
Option 2: Docker
🤖 **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:
If you are telling it about new or updated tasks, you can append this to the end of your prompt:
**Adding tasks while AI works:** To safely add tasks without interfering with AI operations, use the CLI from a separate terminal:
🔧 **Installation Examples**
**Full configuration with custom environment:**
**HTTP transport for remote access:**
First run the server:
Then:
📁 **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 |