Markdown任务卡片管理服务

mcp-md-tasks

An MCP server for managing task cards as local Markdown files — no database, no cloud, just files.

Cards are stored as .md files organized in status folders inside a .tasks/ directory in your project. Everything is human-readable and version-control-friendly.

Features

• File-based storage — cards live as .md files, readable and editable by humans
• 5 status lanes — todo, in-progress, review, done, archived
• Auto-incremented IDs — configurable prefix (e.g. TASK-001, FEAT-042)
• Full markdown — descriptions and comments support markdown
• Zero dependencies beyond the MCP SDK and Zod
• Works per-project — .tasks/ is created automatically inside the project where the agent runs

Requirements

• Bun >= 1.0
• An MCP-compatible client (e.g. Claude Code)

Integration with Claude Code

Add the server to your project's .claude/settings.local.json:

{
  "mcpServers": {
    "md-tasks": {
      "command": "bunx",
      "args": ["@jmlaya/mcp-md-tasks"]
    }
  }
}

That's it. Bunx will download and run the package automatically — no local clone or absolute paths needed.

TASKS_ROOT (optional)

By default the server creates .tasks/ in the working directory of the agent's project (process.cwd()). To point to a different location, set the TASKS_ROOT env var to the full path of the desired .tasks/ directory:

{
  "mcpServers": {
    "md-tasks": {
      "command": "bunx",
      "args": ["@jmlaya/mcp-md-tasks"],
      "env": {
        "TASKS_ROOT": "/absolute/path/to/your/project/.tasks"
      }
    }
  }
}

Local development

If you cloned the repo and want to run the server from source:

bun install

{
  "mcpServers": {
    "md-tasks": {
      "command": "/home/your-user/.bun/bin/bun",
      "args": ["run", "/absolute/path/to/mcp-md-tasks/src/index.ts"]
    }
  }
}

Tip: Find your Bun binary path with echo $(which bun) or ~/.bun/bin/bun.

Directory structure

The first time a tool is called, the server bootstraps the following layout automatically:

your-project/
└── .tasks/
    ├── config.yaml       # ID prefix and counter
    ├── todo/
    │   └── TASK-001.md
    ├── in-progress/
    │   └── TASK-002.md
    ├── review/
    ├── done/
    └── archived/

Card format

Each card is a Markdown file with a YAML frontmatter block, a free-form description, and an optional comments section:

---
id: TASK-001
title: Implement login flow
status: in-progress
due_date: 2026-03-15
created_at: 2026-03-01T10:00:00.000Z
updated_at: 2026-03-01T14:22:00.000Z
---

Users should be able to log in with email + password.
Redirect to dashboard on success, show inline errors on failure.

## Comments

### 2026-03-01 12:00:00
Started working on the auth middleware.

### 2026-03-01 14:22:00
JWT integration done, still need to wire up the frontend form.

Frontmatter fields

Configuration (config.yaml)

id_prefix: TASK
id_counter: 5

Edit this file to change the prefix or reset/continue the counter.

Available tools

* required   ? optional

Status values

todo · in-progress · review · done · archived

Typical workflow

create_card → [todo]
   ↓ move_card
[in-progress]
   ↓ move_card
[review]
   ↓ move_card
[done]

at any point → delete_card → [archived]

An agent can use add_comment to log progress notes at any stage, and search_cards to locate cards across all statuses.

Development

# Run with auto-reload
bun run dev

# Run once
bun run start

Server logs go to stderr only. Stdout is reserved for the MCP JSON-RPC transport.