TaskFlow MCP

TaskFlow MCP is a server that helps AI assistants plan complex requests by breaking them into tasks and subtasks, track progress, require user approvals, and persist data across sessions. It provides a clear workflow for planning, executing, validating, and archiving work, with flexible configuration to fit your project needs.

How to use

You will use TaskFlow MCP with an MCP client to plan user requests, generate task plans, execute tasks, and confirm outcomes with the user. Start by defining a request, let the server break it into tasks and subtasks, complete subtasks, mark tasks done after validation, and obtain user confirmation before moving on. Use the archive features to keep active task files clean while preserving history.

Common usage patterns include: planning a request with a structured set of tasks and notes, retrieving the next pending task, completing subtasks before marking a task as done, and exporting task status reports for reviews or handoffs. You can also manage prompts globally to steer how assistants describe and approach each task.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

# Global installation
npm install -g @pinkpixel/taskflow-mcp

# Local installation (in your project directory)
npm install @pinkpixel/taskflow-mcp

Configuration and operation notes

By default, TaskFlow MCP saves tasks to a file named tasks.yaml in your current working directory. You can customize this path using environment variables when starting the server.

Important environment variables you may use include: TASK_MANAGER_FILE_PATH to specify the tasks file path, TASK_MANAGER_BASE_DIR to set a custom base directory for relative paths, ARCHIVE_FILE_PATH to specify an archive file, and ARCHIVE_MODE to control archiving behavior.

Troubleshooting and tips

If you encounter path resolution issues, TaskFlow MCP handles Windows and Linux paths consistently by resolving and normalizing paths. Ensure parent directories exist for your task file path so the server can save data.

For better readability and manual editing, save data in YAML format by using a .yaml or .yml extension in TASK_MANAGER_FILE_PATH.

Prompts and UX consistency

You can configure a global prompts system to provide instructions, a taskPrefix, and a taskSuffix that are automatically applied to task descriptions. This helps maintain consistent guidance for AI assistants across tasks.

Archive and history management

Use the archive features to move completed requests out of the active file while preserving the full history. You can configure an archive file path and enable automatic archiving on completion if desired.

Example workflow steps

1. Plan a request into tasks and subtasks.

2. Retrieve the next pending task.

3. Complete subtasks before marking the task done.

4. Mark the task done and wait for user confirmation.

5. Repeat until all tasks are completed, then perform a final confirmation.

Export options

Export task plans and status reports in Markdown, JSON, or HTML formats for sharing with team members or stakeholders.

Available tools

plan_task

Register a new user request and plan its associated tasks with optional subtasks, dependencies, and notes.

get_next_task

Retrieve the next pending task for a request.

mark_task_done

Mark a task as completed after all subtasks are finished.

open_task_details

Get details about a specific task.

list_requests

List all requests in the system.

add_tasks_to_request

Add more tasks to an existing request.

update_task

Update a task's title or description.

delete_task

Delete a task from a request.

add_subtasks

Add subtasks to an existing task.

mark_subtask_done

Mark a subtask as completed.

update_subtask

Update a subtask's title or description.

delete_subtask

Delete a subtask from a task.

export_task_status

Export the current status of all tasks in a request to a file.

add_note

Add a note to a request.

update_note

Update an existing note.

delete_note

Delete a note from a request.

add_dependency

Add a dependency to a request or task.

get_prompts

Get the current prompts configuration.

set_prompts

Set the global prompts configuration (replaces existing settings).

update_prompts

Update specific parts of the prompts configuration.

remove_prompts

Remove the entire prompts configuration or specific fields.

archive_completed_requests

Archive completed requests to keep the active file clean.

list_archived_requests

List archived requests with optional search and filtering.

restore_archived_request

Restore an archived request back to active tasks.