{"id":30049202,"url":"https://github.com/flesler/mcp-tasks","last_synced_at":"2025-08-07T11:18:43.824Z","repository":{"id":305519703,"uuid":"1021625336","full_name":"flesler/mcp-tasks","owner":"flesler","description":"A comprehensive and efficient MCP server for task management with multi-format support (Markdown, JSON, YAML)","archived":false,"fork":false,"pushed_at":"2025-08-06T23:15:32.000Z","size":318,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-06T23:22:45.357Z","etag":null,"topics":["ai","claude","claude-ai","claude-code","cursor","llm","mcp","mcp-server","model-context-protocol","task-manager","todo"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flesler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-17T17:24:24.000Z","updated_at":"2025-08-06T23:15:35.000Z","dependencies_parsed_at":"2025-07-20T16:31:33.597Z","dependency_job_id":null,"html_url":"https://github.com/flesler/mcp-tasks","commit_stats":null,"previous_names":["flesler/mcp-tasks"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/flesler/mcp-tasks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flesler%2Fmcp-tasks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flesler%2Fmcp-tasks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flesler%2Fmcp-tasks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flesler%2Fmcp-tasks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flesler","download_url":"https://codeload.github.com/flesler/mcp-tasks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flesler%2Fmcp-tasks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269245153,"owners_count":24384632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-ai","claude-code","cursor","llm","mcp","mcp-server","model-context-protocol","task-manager","todo"],"created_at":"2025-08-07T11:18:43.103Z","updated_at":"2025-08-07T11:18:43.815Z","avatar_url":"https://github.com/flesler.png","language":"TypeScript","funding_links":[],"categories":["Productivity","Community Servers","カテゴリ","📦 Other","Productivity \u0026 Workflow"],"sub_categories":["Tasks \u0026 Calendar","🛠️ \u003ca name=\"developer-tools\"\u003e\u003c/a\u003e開発ツール"],"readme":"# MCP Tasks 📋\n\n[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=mcp-tasks\u0026config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMm5weCUyMC15JTIwbWNwLXRhc2tzJTIyJTdE)\n[![npm version](https://img.shields.io/npm/v/mcp-tasks.svg)](https://www.npmjs.com/package/mcp-tasks)\n[![Node.js](https://img.shields.io/node/v/mcp-tasks.svg)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Docker](https://img.shields.io/docker/v/flesler/mcp-tasks?label=docker)](https://hub.docker.com/r/flesler/mcp-tasks)\n\nAn 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)\n\n## 📚 **Table of Contents**\n\n- [✨ Features](#-features)\n- [🚀 Quick Start](#-quick-start)\n- [🤖 AI Integration Tips](#-ai-integration-tips)\n- [🔧 Installation Examples](#-installation-examples)\n- [📁 Supported File Formats](#-supported-file-formats)\n- [🛠️ Available Tools](#️-available-tools)\n- [🎛️ Environment Variables](#️-environment-variables)\n- [📊 File Formats](#-file-formats)\n- [🖥️ Server Usage](#️-server-usage)\n- [💻 CLI Usage](#-cli-usage)\n- [🧪 Development](#-development)\n- [🛠️ Troubleshooting](#️-troubleshooting)\n- [Why not let AI edit files directly?](#why-not-just-have-ai-edit-the-task-files-directly)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n- [🔗 Links](#-links)\n\n## ✨ **Features**\n\n- ⚡ **Ultra-efficient design**: Minimal tool count (5 tools) to reduce AI confusion\n- 🎯 **Budget-optimized**: Batch operations, smart defaults and auto-operations minimize LLM API calls\n- 🚀 **Multi-format support**: Markdown (`.md`), JSON (`.json`), and YAML (`.yml`) task files\n- 🔍 **Powerful search**: Case-insensitive text/status filtering with OR logic, and ID-based lookup\n- 📊 **Smart organization**: Status-based filtering with customizable workflow states\n- 🎯 **Position-based indexing**: Easy task ordering with 0-based insertion\n- 📁 **Multi-source support**: Manage multiple task files simultaneously\n- 🔄 **Real-time updates**: Changes persist automatically to your chosen format\n- 🤖 **Auto WIP management**: Automatically manages work-in-progress task limits\n- 🚫 **Duplicate prevention**: Automatically prevents duplicate tasks\n- 🛡️ **Type-safe**: Full TypeScript support with Zod validation\n- 🔒 **Ultra-safe**: AI has no way to rewrite or delete your tasks (unless you enable it), only add and move them\n- 📅 **Optional reminders**: Enable a dedicated Reminders section the AI constantly sees and can maintain\n\n## 🚀 **Quick Start**\n\nAdd this to `~/.cursor/mcp.json` for Cursor, `~/.config/claude_desktop_config.json` for Claude Desktop.\n\n### Option 1: NPX (Recommended)\n```json\n{\n  \"mcpServers\": {\n    \"mcp-tasks\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-tasks\"]\n    }\n  }\n}\n```\n\n### Option 2: Docker\n```json\n{\n  \"mcpServers\": {\n    \"mcp-tasks\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"flesler/mcp-tasks\"\n      ]\n    }\n  }\n}\n```\n\n## 🤖 **AI Integration Tips**\n\nTo 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:\n\n```\nUse mcp-tasks tools to track our work in path/to/tasks.md\n```\n\nIf you are telling it about new or updated tasks, you can append this to the end of your prompt:\n\n```\nuse mcp-tasks\n```\n\n**Adding tasks while AI works:** To safely add tasks without interfering with AI operations, [use the CLI](#-cli-usage) from a separate terminal:\n\n```bash\nnpx mcp-tasks add \"Your new task text\" \"To Do\" 0\n```\n\n\n## 🔧 **Installation Examples**\n\n**Full configuration with custom environment:**\n```json\n{\n  \"mcpServers\": {\n    \"mcp-tasks\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-tasks\"],\n      \"env\": {\n        \"STATUS_WIP\": \"In Progress\",\n        \"STATUS_TODO\": \"To Do\",\n        \"STATUS_DONE\": \"Done\",\n        \"STATUS_REMINDERS\": \"Reminders\",\n        \"STATUS_NOTES\": \"Notes\",\n        \"STATUSES\": \"In Progress,To Do,Done,Backlog,Reminders,Notes\",\n        \"AUTO_WIP\": \"true\",\n        \"PREFIX_TOOLS\": \"true\",\n        \"KEEP_DELETED\": \"true\",\n        \"TRANSPORT\": \"stdio\",\n        \"PORT\": \"4680\",\n        \"INSTRUCTIONS\": \"Use mcp-tasks tools when the user mentions new or updated tasks\"\n      }\n    }\n  }\n}\n```\n\n**HTTP transport for remote access:**\n\nFirst run the server:\n```bash\nTRANSPORT=http PORT=4680 npx mcp-tasks\n```\nThen:\n```json\n{\n  \"mcpServers\": {\n    \"mcp-tasks\": {\n      \"type\": \"streamableHttp\",\n      \"url\": \"http://localhost:4680/mcp\"\n    }\n  }\n}\n```\n\n## 📁 **Supported File Formats**\n\n| Extension | Format | Best For | Auto-Created |\n|-----------|--------|----------|--------------|\n| `.md` | Markdown | Human-readable task lists | ✅ |\n| `.json` | JSON | Structured data, APIs | ✅ |\n| `.yml` | YAML | Configuration files | ✅ |\n\n**Format is auto-detected from file extension.** All formats support the same features and can be mixed in the same project.\n\n**Recommended**: Markdown (`.md`) for human readability and editing\n\n**⚠️ Warning**: Start with a new file rather than using pre-existing task files to avoid losing non-task content.\n\n## 🛠️ **Available Tools**\n\nWhen `PREFIX_TOOLS=true` (default), all tools are prefixed with `tasks_`:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `tasks_setup` | Initialize a task file (creates if missing, supports `.md`, `.json`, `.yml`) | `source_path`, `workspace?` |\n| `tasks_search` | Search tasks with filtering | `source_id`, `statuses?`, `terms?`, `ids?` |\n| `tasks_add` | Add new tasks to a status | `source_id`, `texts[]`, `status`, `index?` |\n| `tasks_update` | Update tasks by ID | `source_id`, `ids[]`, `status`, `index?` |\n| `tasks_summary` | Get task counts and work-in-progress | `source_id` |\n\n**ID Format**: Both `source_id` (from file path) and task `id` (from task text) are 4-character alphanumeric strings (e.g., `\"xK8p\"`, `\"m3Qw\"`).\n\n### Tool Examples\n\n**Setup a task file:**\n```javascript\ntasks_setup({\n  workspace: \"/path/to/project\",\n  source_path: \"tasks.md\"  // relative to workspace or absolute\n  // source_path: \"tasks.json\"\n  // source_path: \"tasks.yml\"\n})\n// Returns: {\"source\":{\"id\":\"xK8p\",\"path\":\"/path/to/project/tasks.md\"},\"Backlog\":0,\"To Do\":0,\"In Progress\":0,\"Done\":0,\"inProgress\":[]}\n// Source ID (4-char alphanumeric) is used for all subsequent operations\n```\n\n**Add tasks:**\n```javascript\ntasks_add({\n  source_id: \"xK8p\", // From setup response\n  texts: [\"Implement authentication\", \"Write tests\"],\n  status: \"To Do\",\n  index: 0  // Add at top (optional)\n})\n// 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}]}\n```\n\n**Search and filter:**\n```javascript\ntasks_search({\n  source_id: \"xK8p\",        // From setup response\n  terms: [\"auth\", \"deploy\"],          // Search terms (text or status, OR logic)\n  statuses: [\"To Do\"],      // Filter by status\n  ids: [\"m3Qw\", \"p9Lx\"]     // Filter by specific task IDs\n})\n// Returns: [{\"id\":\"m3Qw\",\"text\":\"Implement authentication\",\"status\":\"To Do\",\"index\":0}]\n```\n\n**Update tasks status:**\n```javascript\ntasks_update({\n  source_id: \"xK8p\",        // From setup response\n  ids: [\"m3Qw\", \"p9Lx\"],    // Task IDs from add/search responses\n  status: \"Done\"            // Use \"Deleted\" to remove\n})\n// 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}]}\n```\n\n**Get overview:**\n```javascript\ntasks_summary({\n  source_id: \"xK8p\"         // From setup response\n})\n// 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}]}\n```\n\n## 🎛️ **Environment Variables**\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |\n| `PORT` | `4680` | HTTP server port (when `TRANSPORT=http`) |\n| `PREFIX_TOOLS` | `true` | Prefix tool names with `tasks_` |\n| `STATUS_WIP` | `In Progress` | Work-in-progress status name |\n| `STATUS_TODO` | `To Do` | ToDo status name |\n| `STATUS_DONE` | `Done` | Completed status name |\n| `STATUS_REMINDERS` | `Reminders` | Reminders for the AI (empty string to disable) |\n| `STATUS_NOTES` | `Notes` | Notes/non-actionable tasks (empty string to disable) |\n| `STATUSES` | `Backlog` | Comma-separated additional statuses |\n| `AUTO_WIP` | `true` | One WIP moves rest to To Do, first To Do to WIP when no WIP's |\n| `KEEP_DELETED` | `true` | Retain deleted tasks (AI can't lose you tasks!) |\n| `INSTRUCTIONS` | `...` | Included in all tool responses, for the AI to follow |\n| `SOURCES_PATH` | `./sources.json` | File to store source registry (internal) |\n| `DEBUG` | `false` | if true, enable the `tasks_debug` tool |\n\n### Advanced Configuration Examples\n\nOptional, the WIP/ToDo/Done statuses can be included to control their order.\n\n**Custom workflow statuses:**\n```json\n{\n  \"env\": {\n    \"STATUSES\": \"WIP,Pending,Archived,Done,To Review\",\n    \"STATUS_WIP\": \"WIP\",\n    \"STATUS_TODO\": \"Pending\",\n    \"AUTO_WIP\": \"false\"\n  }\n}\n```\n\n## 📊 **File Formats**\n\n### Markdown (`.md`) - Human-Readable\n```markdown\n# Tasks - File Name\n\n## In Progress\n- [ ] Write user registration\n\n## To Do\n- [ ] Implement authentication\n- [ ] Set up CI/CD pipeline\n\n## Backlog\n- [ ] Plan architecture\n- [ ] Design database schema\n\n## Done\n- [x] Set up project structure\n- [x] Initialize repository\n\n## Reminders\n- [ ] Don't move to Done until you verified it works\n- [ ] After you move to Done, commit all the changes, use the task name as the commit message\n\n## Notes\n- [ ] The task tools were really great to use!\n```\n\n### JSON (`.json`) - Structured Data\n```json\n{\n  \"groups\": {\n    \"In Progress\": [\n      \"Write user registration\"\n    ],\n    \"To Do\": [\n      \"Implement authentication\",\n      \"Set up CI/CD pipeline\"\n    ],\n    \"Backlog\": [\n      \"Plan architecture\",\n      \"Design database schema\"\n    ],\n    \"Done\": [\n      \"Set up project structure\",\n      \"Initialize repository\"\n    ],\n    \"Reminders\": [\n      \"Don't move to Done until you verified it works\",\n      \"After you move to Done, commit all the changes, use the task name as the commit message\"\n    ],\n    \"Notes\": [\n      \"The task tools were really great to use!\"\n    ]\n  }\n}\n```\n\n### YAML (`.yml`) - Configuration-Friendly\n```yaml\ngroups:\n  \"In Progress\":\n    - Write user registration\n  \"To Do\":\n    - Implement authentication\n    - Set up CI/CD pipeline\n  Backlog:\n    - Plan architecture\n    - Design database schema\n  Done:\n    - Set up project structure\n    - Initialize repository\n  Reminders:\n    - Don't move to Done until you verified it works\n    - After you move to Done, commit all the changes, use the task name as the commit message\n```\n\n## 🖥️ **Server Usage**\n\n```bash\n# Show help\nmcp-tasks --help\n\n# Default: stdio transport\nmcp-tasks\n\n# HTTP transport\nTRANSPORT=http mcp-tasks\nTRANSPORT=http PORT=8080 mcp-tasks\n\n# Custom configuration\nSTATUS_WIP=\"Working\" AUTO_WIP=false mcp-tasks\n```\n\n## 💻 **CLI Usage**\n\nYou can also use `mcp-tasks` (or `npx mcp-tasks`) as a command-line tool for quick task management:\n\n```bash\n# Setup a task file\nmcp-tasks setup tasks.md $PWD                      # Setup with workspace\n\n# Add tasks\nmcp-tasks add \"Implement authentication\"           # Defaults to \"To Do\" status\nmcp-tasks add \"Write tests\" \"Backlog\"              # Add with specific status\nmcp-tasks add \"Fix critical bug\" \"In Progress\" 0   # Add at top (index 0)\n\n# Search tasks\nmcp-tasks search                                    # All tasks\nmcp-tasks search \"\" \"auth,login\"                   # Search for specific terms\nmcp-tasks search \"To Do,Done\" \"\"                   # Filter by statuses\nmcp-tasks search \"In Progress\" \"bug\"               # Filter by status and search terms\n\n# Update task status (comma-separated IDs)\nmcp-tasks update m3Qw,p9Lx Done\n\n# Get summary\nmcp-tasks summary\n\n# Add a reminder (feature must be enabled with REMINDERS=true)\nmcp-tasks add \"Don't move to Done until you verified it works\" Reminders\n```\n\n**CLI Features:**\n- Direct access to all MCP tool functionality\n- JSON output for easy parsing and scripting\n- Same reliability and duplicate prevention as MCP tools\n- Perfect for automation scripts and CI/CD pipelines\n\n## 🧪 **Development**\n\n```bash\n# Clone and setup\ngit clone https://github.com/flesler/mcp-tasks\ncd mcp-tasks\nnpm install\n\n# Development mode (auto-restart)\nnpm run dev              # STDIO transport\nnpm run dev:http         # HTTP transport on port 4680\n\n# Build and test\nnpm run build           # Compile TypeScript\nnpm run lint            # Check code style\nnpm run lint:full       # Build + lint\n```\n\n## 🛠️ **Troubleshooting**\n\n### **Requirements**\n- **Node.js ≥20** - This package requires Node.js version 20 or higher\n\n### **Common Issues**\n\n**ERR_MODULE_NOT_FOUND when running `npx-tasks`**\n- **Problem**: Error like `Cannot find module '@modelcontextprotocol/sdk/dist/esm/server/index.js'` when running `npx mcp-tasks`\n- **Cause**: Corrupt or incomplete npx cache preventing proper dependency resolution\n- **Solution**: Clear the npx cache and try again:\n  ```bash\n  npx clear-npx-cache\n  npx mcp-tasks\n  ```\n- **Note**: This issue can occur on both Node.js v20 and v22, and the cache clear resolves it\n\n**Where are my tasks stored?**\n- Tasks are stored in the file path you specified by the AI in `tasks_setup`\n- The absolute path is returned in every tool call response under `source.path`\n- If you forgot the location, check any tool response or ask the AI to show it to you\n\n**Lost content in Markdown files:**\n- ⚠️ The tools will rewrite the entire file, preserving only tasks under recognized status sections\n- Non-task content (notes, documentation) may be lost when tools modify the file\n- Use a dedicated task file rather than mixing tasks with other content\n\n## Why not just have AI edit the task files directly?\n\n- **File parsing complexity:** AI must read entire files, parse markdown structure, and understand current state - expensive and error-prone\n- **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\n- **Context loss:** Large task files forcing AI to work with incomplete chunks due to token restrictions and lose track of overall structure\n- **State comprehension:** AI struggles to understand true project state when reading fragmented file sections - which tasks are actually in progress?\n- **Edit precision:** Manual editing risks corrupting markdown formatting, losing tasks, or accidentally modifying the wrong sections\n- **Concurrent editing conflicts:** When AI directly edits files, humans can't safely make manual changes without creating conflicts or overwrites\n- **Token inefficiency:** Reading+parsing+editing cycles consume far more tokens than structured tool calls with clear inputs/outputs\n- **Safety:** AI can accidentally change or delete tasks when directly editing files, but with these tools it cannot rewrite or delete your tasks\n\n## 🤝 **Contributing**\n\nWe welcome contributions! Please:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes with tests\n4. Run: `npm run lint:full`\n5. Submit a pull request\n\n## 📄 **License**\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🔗 **Links**\n\n- 📦 **[NPM Package](https://www.npmjs.com/package/mcp-tasks)**\n- 🐙 **[GitHub Repository](https://github.com/flesler/mcp-tasks)**\n- 🐛 **[Report Issues](https://github.com/flesler/mcp-tasks/issues)**\n- 📚 **[MCP Specification](https://modelcontextprotocol.io/)**\n- ⚡ **[FastMCP Framework](https://github.com/punkpeye/fastmcp)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflesler%2Fmcp-tasks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflesler%2Fmcp-tasks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflesler%2Fmcp-tasks/lists"}