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

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

1. 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"
      }
    }
  }
}

1. 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:

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

# 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