Cursor Taskmaster MCP Server

A comprehensive MCP (Model Context Protocol) server designed to enhance agentic workflows through project-scoped task management, memory retrieval, and intelligent workflow execution.

🎯 Overview

Cursor Taskmaster transforms your development workflow by providing:

• Project-Scoped Storage: All data stored in .taskmaster/ directory within your project
• Hierarchical Task Management: Organize tasks in prompt → task → subtask structure
• Memory Retrieval System: Semantic search and context management for your project
• Agent Workflow Engine: Parse prompts, generate tasks, execute with user approval
• User Approval Workflow: Review and modify tasks before execution

🏗️ Architecture

The system uses a hierarchical approach:

Project Root/
├── .taskmaster/
│   ├── tasks.json      # Hierarchical task storage
│   ├── prompts.json    # Prompt definitions and metadata
│   ├── lists.json      # Task list management
│   ├── workflow.json   # Workflow state and execution log
│   ├── memories.db     # SQLite database for memory storage
│   └── vectors.index/  # Vector embeddings for semantic search

🚀 Features

Task Management

• Create, read, update, delete tasks with hierarchical structure
• Task status tracking (pending, in_progress, completed, failed, awaiting_approval)
• Priority levels (low, medium, high, critical)
• Time estimation and tracking
• Rich metadata support

Memory System

• Project-scoped memory storage with semantic search
• Automatic vectorization using Sentence Transformers
• Context retrieval with similarity thresholds
• Metadata tagging and filtering

Workflow Engine

• Parse natural language prompts into structured tasks
• Sequential task execution with error handling
• User approval checkpoints
• Workflow state persistence and resumption
• Comprehensive execution logging

📋 Available Tools

Task Management Tools

createTask

Create a new task in the project's task management system.

{
  "title": "Task title",
  "description": "Detailed description",
  "priority": "medium",
  "parentId": "optional-parent-task-id",
  "dueDate": "2024-01-01T00:00:00Z",
  "estimatedTime": 60,
  "metadata": { "key": "value" }
}

getTask

Retrieve a specific task by ID.

getAllTasks

Retrieve all tasks in the project.

updateTask

Update an existing task's properties.

deleteTask

Delete a task and all its subtasks.

getTaskHierarchy

Get hierarchical view of tasks with optional root task filter.

Memory Tools

storeMemory

Store information with automatic vectorization for semantic search.

{
  "key": "unique-identifier",
  "content": "Content to store",
  "metadata": { "tags": ["tag1", "tag2"] }
}

retrieveMemory

Retrieve relevant memories using semantic search.

{
  "query": "search query",
  "limit": 5,
  "threshold": 0.7
}

Workflow Tools

parsePrompt

Parse a user query into a structured task workflow.

{
  "query": "Create a REST API with authentication",
  "title": "API Development",
  "description": "Build secure REST API"
}

executeWorkflow

Execute a workflow from a parsed prompt.

approveTask

Approve a task for execution.

rejectTask

Reject a task with optional modifications.

resumeWorkflow

Resume workflow execution from a checkpoint.

getWorkflowState

Get the current workflow execution state.

List Management Tools

getAllPrompts

Get all prompts in the project.

getAllLists

Get all task lists in the project.

🔄 Workflow Process

1. Parse Prompt: Convert natural language query into structured tasks
2. User Review: Tasks marked as awaiting_approval for user review
3. Approval/Modification: User can approve, reject, or modify tasks
4. Sequential Execution: Execute approved tasks in hierarchical order
5. Progress Tracking: Monitor execution with detailed logging
6. Error Handling: Pause on errors with recovery options
7. Memory Storage: Store execution context and results

📦 Installation

For Cursor Users (Recommended)

No installation needed! Just configure Cursor to use the npm package directly:

{
  "mcpServers": {
    "cursor-taskmaster": {
      "command": "npx",
      "args": [
        "@notbnull/mcp-cursor-taskmaster",
        "--project-dir",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

Replace /absolute/path/to/your/project with your actual project path!

For Development

git clone <repository-url>
cd mcp-cursor-taskmaster
npm install
npm run build

⚙️ Configuration

🎯 Project Directory Configuration (Important!)

Due to how MCP servers work, Cursor cannot automatically detect your project directory. You have two options:

Option 1: Specify Your Project Directory (Recommended)

{
  "mcpServers": {
    "cursor-taskmaster": {
      "command": "npx",
      "args": [
        "@notbnull/mcp-cursor-taskmaster",
        "--project-dir",
        "/path/to/your/actual/project"
      ]
    }
  }
}

This will create .taskmaster/ in your specified project directory.

Option 2: Use Default Fallback Directory

{
  "mcpServers": {
    "cursor-taskmaster": {
      "command": "npx",
      "args": ["@notbnull/mcp-cursor-taskmaster"]
    }
  }
}

This will create .taskmaster/ in ~/cursor-taskmaster-projects/ as a fallback.

⚠️ Important: If you don't specify --project-dir, your tasks and memories will be stored in the fallback directory, not your actual project!

🛠️ Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Lint code
npm run lint

📁 Project Structure

src/
├── index.ts           # Main MCP server implementation
├── task-store.ts      # Task management and storage
├── workflow-engine.ts # Workflow execution engine
├── memory-store.ts    # Memory storage with SQLite
└── vector-store.ts    # Vector embeddings and search

🤖 Usage Examples

Basic Task Creation

// Create a main task
const task = await tools.createTask({
  title: "Build Authentication System",
  description: "Implement JWT-based authentication",
  priority: "high",
  estimatedTime: 240,
});

// Create subtasks
await tools.createTask({
  title: "Create User Model",
  description: "Define user schema and database model",
  parentId: task.id,
  priority: "medium",
  estimatedTime: 60,
});

Workflow Automation

// Parse user query into tasks
const result = await tools.parsePrompt({
  query: "Set up a React app with TypeScript and testing",
  title: "React App Setup",
});

// Review and approve tasks
await tools.approveTask(taskId, "Looks good!");

// Execute the workflow
await tools.executeWorkflow(result.promptId);

Memory Management

// Store project knowledge
await tools.storeMemory({
  key: "api_endpoints",
  content:
    "User authentication endpoints: POST /auth/login, POST /auth/register",
  metadata: { type: "api_documentation", module: "auth" },
});

// Retrieve relevant context
const memories = await tools.retrieveMemory({
  query: "authentication endpoints",
  limit: 3,
});

🔐 Security

• All data stored locally in project directory
• No external API calls for core functionality
• Vector embeddings computed locally using Sentence Transformers

🔧 Troubleshooting

My .taskmaster directory is not in my project!

This is the most common issue. Cursor cannot automatically detect your project directory when running MCP servers. You must specify it explicitly:

{
  "mcpServers": {
    "cursor-taskmaster": {
      "command": "npx",
      "args": [
        "@notbnull/mcp-cursor-taskmaster",
        "--project-dir",
        "/Users/yourname/path/to/your/actual/project"
      ]
    }
  }
}

How to find your project path:

1. Open terminal in your project
2. Run pwd to get the full path
3. Use that exact path in the configuration

Why can't it auto-detect my project?

MCP servers run in a separate process context without access to Cursor's working directory. This is a limitation of the MCP protocol, not our server. The explicit path configuration is the most reliable solution.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol
• Uses Sentence Transformers for embeddings
• Powered by SQLite for reliable data storage

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: Check this README and inline code documentation
• Examples: See the examples/ directory for usage patterns