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

Clone and Install

git clone <this-repo> cd tasks-md-mcp npm install

Configure MCP Server

For Kilocode/IDE (.kilocode/mcp.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):

{ "mcpServers": { "mcp-tasks": { "command": "npx", "args": ["-y", "mcp-tasks"], "env": { "TASKS_DIR": "./demo-project" } } } }

Start Using

# 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:

Example Files

Epic (epic-01-auth.md):

# 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):

# 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):

# 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

./scripts/refresh-status.sh [project-dir]

Generates status-board.md from tasks.md with current task statuses.

Create New Ticket

cp scripts/ticket_template.md demo-project/task-new.md # Edit and customize

Progress Report

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

npm install # or bun install

Start MCP Server

npm start # or npx mcp-tasks

Useful Commands

# 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:

# 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):

# 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

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
Review example projects in demo-project/

Built with ❤️ for AI-native development