Tasks.md MCP Server

# Tasks.md MCP Server **Markdown-based task management for Claude via Model Context Protocol (MCP)** A lightweight, AI-native task management system that uses plain markdown files to track Epics, Stories, Tasks, and Milestones. Claude can create, update, query, and organize tasks through MCP tools without requiring a database. ## Features ✅ **Simple**: Just markdown files - no complex setup ✅ **Flexible**: Customize structure and workflows ✅ **AI-Native**: Built for Claude integration via MCP ✅ **Git-Friendly**: Version control your tasks naturally ✅ **Portable**: Plain text - import/export anywhere ✅ **Scriptable**: Automate with standard CLI tools ## Quick Start ### Prerequisites - Node.js 18+ or Bun - npm or bun package manager - Claude Desktop or Claude Code with MCP support ### Installation 1. **Clone and Install** ```bash git clone <this-repo> cd tasks-md-mcp npm install ``` 2. **Configure MCP Server** For **Kilocode/IDE** (`.kilocode/mcp.json`): ```json { "mcpServers": { "mcp-tasks": { "command": "./node_modules/.bin/mcp-tasks", "args": [], "env": { "TRANSPORT": "http", "PORT": "3211", "TASKS_DIR": "./demo-project" } } } } ``` For **Claude Code** (`.claude/settings.json`): ```json { "mcpServers": { "mcp-tasks": { "command": "npx", "args": ["-y", "mcp-tasks"], "env": { "TASKS_DIR": "./demo-project" } } } } ``` 3. **Start Using** ```bash # Start MCP server npm start # Or refresh status board npm run refresh-status ``` ## Project Structure ``` tasks-md-mcp/ ├── demo-project/ # Example task project │ ├── tasks.md # Main task index (all tasks) │ ├── summary.json # Project statistics │ ├── status-board.md # Status overview │ ├── epic-*.md # Epic files │ ├── story-*.md # Story files │ ├── task-*.md # Task files │ └── milestone-*.md # Milestone files ├── scripts/ # Utility scripts │ ├── refresh-status.sh # Update status board │ ├── ticket_template.md # New ticket template │ └── progress_report.md # Progress report template ├── .kilocode/ │ └── mcp.json # MCP server configuration ├── .claude/ │ └── settings.json # Claude Code configuration └── package.json # Dependencies ``` ## File Naming Conventions ### Epic Files ``` epic-[ID]-[slug].md Example: epic-01-auth.md ``` ### Story Files ``` story-[EPIC_ID]-[STORY_NUM].md Example: story-01-01.md (Epic 01, Story 01) ``` ### Task Files ``` task-[EPIC_ID]-[STORY_ID]-[TASK_NUM].md Example: task-01-01-01.md (Epic 01, Story 01, Task 01) ``` ### Milestone Files ``` milestone-[slug].md Example: milestone-v1-0.md ``` ## Task File Format Every task file follows this structure: ```markdown # [TYPE]: [ID] — [Title] [Description - 2-4 sentences explaining the task, acceptance criteria, and context] Server ID: [alphanumeric] Status: [Backlog|To Do|In Progress|Done|Notes|Deleted] ``` ### Example Files **Epic** (`epic-01-auth.md`): ```markdown # EPIC: AUTH-01 — Authentication epic A top-level epic that groups authentication-related work such as signup, login, and password recovery. It captures high-level goals and acceptance criteria for the authentication area. Server ID: jntg Status: Backlog ``` **Story** (`story-01-01.md`): ```markdown # STORY: AUTH-01-1 — Signup flow Implement user signup functionality including email validation, password strength checking, and account creation. Should integrate with the authentication epic's overall architecture. Server ID: xK9p Status: To Do ``` **Task** (`task-01-01-01.md`): ```markdown # TASK: AUTH-01-1-1 — Implement signup endpoint Create POST /api/signup endpoint that accepts email and password, validates input, hashes password with bcrypt, and stores user in database. Return JWT token on success. Server ID: mN4r Status: In Progress ``` ## Usage with Claude Once the MCP server is configured and running, you can ask Claude to manage tasks: ### Creating Tasks ``` "Create a new epic for user authentication" → Creates epic-XX-auth.md with proper structure "Add a story to epic AUTH-01 for signup flow" → Creates story-01-XX.md under the epic "Create task for implementing signup endpoint" → Creates task-01-XX-XX.md with metadata ``` ### Querying Tasks ``` "Show me all tasks in progress" → Queries tasks.md and returns current work "What tasks are in the authentication epic?" → Lists all AUTH-01 related items "Generate a progress report" → Analyzes tasks and creates report ``` ### Updating Tasks ``` "Move task AUTH-01-1-1 to Done" → Updates task file and tasks.md index "Update the signup story description" → Modifies story-01-01.md content ``` ## Helper Scripts ### Refresh Status Board ```bash ./scripts/refresh-status.sh [project-dir] ``` Generates `status-board.md` from `tasks.md` with current task statuses. ### Create New Ticket ```bash cp scripts/ticket_template.md demo-project/task-new.md # Edit and customize ``` ### Progress Report ```bash cp scripts/progress_report.md reports/weekly-$(date +%Y-%m-%d).md # Fill in metrics ``` ## Task Statuses - **Backlog**: Not yet prioritized - **To Do**: Ready to start - **In Progress**: Currently being worked on - **Done**: Completed - **Notes**: Planning notes and ideas - **Deleted**: Removed tasks (kept for history) ## MCP Tools Available When Claude connects to the mcp-tasks server, these tools become available: ### Task Creation - `create_epic` - Create new epic with auto-generated ID - `create_story` - Create story under an epic - `create_task` - Create task under a story - `create_milestone` - Create project milestone ### Task Management - `update_task` - Update task title, description, or status - `move_task` - Change task status - `delete_task` - Mark task as deleted - `assign_task` - Assign task to team member ### Querying - `list_tasks` - List all tasks with filtering - `get_task` - Get detailed task information - `search_tasks` - Search tasks by keyword - `get_summary` - Get project statistics ### Organization - `link_tasks` - Create dependency between tasks - `add_tag` - Tag tasks with labels - `bulk_update` - Update multiple tasks ## Development ### Install Dependencies ```bash npm install # or bun install ``` ### Start MCP Server ```bash npm start # or npx mcp-tasks ``` ### Useful Commands ```bash # Refresh status board npm run refresh-status # View project summary cat demo-project/summary.json | jq # Search tasks grep -r "In Progress" demo-project/*.md # List all epics ls demo-project/epic-*.md ``` ## Git Integration Tasks are stored as plain markdown files, making them perfect for version control: ```bash # Track task changes git add demo-project/*.md git commit -m "feat: add authentication epic and stories" # Create branch per epic git checkout -b epic/auth-01 # Review task changes git diff demo-project/tasks.md ``` ## Configuration ### Environment Variables Create `.env` file (optional): ```bash # Task Directory TASKS_DIR="./demo-project" # Server Configuration TRANSPORT="http" PORT="3211" # Git Integration AUTO_COMMIT="false" GIT_AUTHOR_NAME="Task Bot" GIT_AUTHOR_EMAIL="bot@tasks.md" ``` ## Why Use Tasks.md? ### For Developers - Git-friendly task tracking (plain markdown files) - No database setup required - Works with any text editor - Easy to backup and migrate - Scriptable with standard CLI tools ### For AI Assistants (Claude) - Natural language task management - Automatic file generation and updates - Intelligent task querying and filtering - Progress tracking and reporting - Template-based task creation ### For Teams - Transparent task history (version controlled) - Flexible workflow (customize status types) - Portable data (not locked in proprietary format) - Simple onboarding (just markdown files) - Integrates with existing tools (CI/CD, webhooks) ## Examples ### Project Initialization ```bash mkdir my-saas-project && cd my-saas-project npm install mcp-tasks npx mcp-tasks init ``` Then ask Claude: > "Set up initial epics for authentication, payments, and admin dashboard" ### Sprint Planning > "Create sprint plan for authentication epic" Claude creates: - EPIC: AUTH-01 — User Authentication - STORY: AUTH-01-1 — User signup - STORY: AUTH-01-2 — User login - STORY: AUTH-01-3 — Password recovery - Multiple tasks under each story ### Daily Standup > "What tasks are in progress and who's blocked?" Claude responds with current status and blockers. ### Weekly Progress > "Generate weekly progress report" Claude analyzes tasks and creates comprehensive report. ## License MIT ## Contributing Contributions welcome! Please read the contributing guidelines before submitting PRs. ## Support For issues or questions: - Open an issue on GitHub - Check the [MCP Tasks documentation](https://github.com/modelcontextprotocol/servers/tree/main/src/tasks) - Review example projects in `demo-project/` --- **Built with ❤️ for AI-native development**