btm-mcp

MCP server for Bash Task Master (BTM). It gives AI assistants (e.g. in Cursor) the tools and resources to write and iterate on BTM task definitions; running tasks is supported so the AI can verify behavior after editing.

Purpose

The main purpose of this MCP is writing tasks, not running them. Running is already easy from the terminal and the VSCode/Cursor extension. This server exposes:

• Tools so the model can discover the task file, create one, validate syntax, list tasks, get task help, and run a task to verify.
• Resource btm://docs/syntax – a concise “how to write BTM tasks” doc so the model has the correct syntax when generating or editing tasks.sh / .tasks.sh.

Requirements

• Node.js 18+
• BTM installed and configured (TASK_MASTER_HOME or default under home)
• Bash (for running BTM)

Install and build

cd btm-mcp
npm install
npm run build

Run

Stdio (for Cursor or other MCP clients that spawn the server):

node dist/index.js

Cursor integration

Add to your Cursor MCP settings (e.g. in .cursor/mcp.json or Cursor settings) a server that runs the btm-mcp process over stdio:

{
  "mcpServers": {
    "btm": {
      "command": "node",
      "args": ["/absolute/path/to/btm-mcp/dist/index.js"],
      "env": {
        "TASK_MASTER_HOME": "/path/to/your/btm/home"
      }
    }
  }
}

Leave TASK_MASTER_HOME unset to use the default (e.g. ~ or your BTM install path).

Tools

Tool	Purpose
get_task_file_info	Path and existence of the task file for a directory (walk up for tasks.sh / .tasks.sh)
init_task_file	Create a new task file (task init)
validate_task_file	Validate task file syntax (bash -n) and return errors
list_tasks	List tasks (scope: all, local, global, modules)
task_help	Get structured help (description, required/optional args, subcommands) for a task
run_task	Run a task and return stdout, stderr, exit code

Resource

• btm://docs/syntax – Markdown doc describing how to write BTM tasks (task_ prefix, arguments_*, REQUIREMENTS/OPTIONS, task_spec, has_arg, subcommands, argument types).

License

Same as Bash Task Master (see parent repo).