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)

{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"]
    }
  }
}

Option 2: Docker

{
  "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 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 

... [View full README on GitHub](https://github.com/flesler/mcp-tasks#readme)