A comprehensive MCP (Model Context Protocol) server designed to enhance agentic workflows through project-scoped task management, memory retrieval, and intelligent workflow execution.
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
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
- 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
- NEW: Interactive approval UI for task review and modification
- Project-scoped memory storage with text search
- Optional semantic search with automatic vectorization (when available)
- Context retrieval with similarity thresholds or basic text matching
- Metadata tagging and filtering
- Parse natural language prompts into structured tasks
- Sequential task execution with error handling
- User approval checkpoints with web-based UI
- Workflow state persistence and resumption
- NEW: Automatic detection of project directory using multiple methods:
- Environment variables (CURSOR_PROJECT_DIR, PWD, etc.)
- Command-line arguments (--project-dir)
- Project file indicators (.git, package.json, etc.)
- Intelligent fallback to user home directory
- Comprehensive execution logging
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" }
}Retrieve a specific task by ID.
Retrieve all tasks in the project.
Update an existing task's properties.
Delete a task and all its subtasks.
Get hierarchical view of tasks with optional root task filter.
Store information with automatic vectorization for semantic search.
{
"key": "unique-identifier",
"content": "Content to store",
"metadata": { "tags": ["tag1", "tag2"] }
}Retrieve relevant memories using semantic search.
{
"query": "search query",
"limit": 5,
"threshold": 0.7
}Parse a user query into a structured task workflow.
{
"query": "Create a REST API with authentication",
"title": "API Development",
"description": "Build secure REST API"
}Execute a workflow from a parsed prompt.
Approve a task for execution.
Reject a task with optional modifications.
Resume workflow execution from a checkpoint.
Get the current workflow execution state.
Get all prompts in the project.
Get all task lists in the project.
- Parse Prompt: Convert natural language query into structured tasks
- User Review: Tasks marked as
awaiting_approvalfor user review - Approval/Modification: User can approve, reject, or modify tasks
- Sequential Execution: Execute approved tasks in hierarchical order
- Progress Tracking: Monitor execution with detailed logging
- Error Handling: Pause on errors with recovery options
- Memory Storage: Store execution context and results
Install and configure the MCP server in your project using NPM:
{
"mcpServers": {
"mcp-cursor-taskmaster": {
"command": "npx",
"args": [
"@notbnull/mcp-cursor-taskmaster",
"--project-dir",
"${workspaceFolder}"
],
"env": {
"NODE_ENV": "production"
}
}
}
}Add this configuration to your project's .cursor/mcp.json file.
If you're contributing to this MCP server:
git clone <repository-url>
cd mcp-cursor-taskmaster
npm install
npm run build- 🎯 Project-Scoped: All data is stored within your project's
.taskmaster/directory - 🚫 No Environment Variables: Configuration is passed via command line arguments
- 📦 NPM Package: Uses the published NPM package for easy installation
- 🔒 Secure: No global data storage or dependencies on external configuration
To enable the interactive task approval UI, add the --enable-approval-ui flag:
{
"mcpServers": {
"mcp-cursor-taskmaster": {
"command": "npx",
"args": [
"@notbnull/mcp-cursor-taskmaster",
"--project-dir",
"${workspaceFolder}",
"--enable-approval-ui"
],
"env": {
"NODE_ENV": "production"
}
}
}
}If you need to specify a different project directory:
{
"mcpServers": {
"mcp-cursor-taskmaster": {
"command": "npx",
"args": [
"@notbnull/mcp-cursor-taskmaster",
"--project-dir",
"/path/to/your/project"
],
"env": {
"NODE_ENV": "production"
}
}
}
}Task Approval UI (when enabled):
- Review task details before execution
- Edit task properties (title, description, priority, etc.)
- Approve, reject, or modify tasks
- Add feedback or comments
- Real-time updates via WebSocket
# 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 lintsrc/
├── 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
Here's a comprehensive system prompt you can use to help AI assistants effectively utilize the Cursor Taskmaster:
## Cursor Taskmaster Integration
You have access to a powerful project-scoped task management and memory system through the Cursor Taskmaster MCP server. Use these capabilities to enhance development workflows.
### Available Tools Overview
**Task Management:**
- `createTask` - Create hierarchical tasks with priorities, time estimates, and metadata
- `getTask` - Retrieve specific task details
- `getAllTasks` - List all tasks in the project
- `updateTask` - Modify task status, priorities, or details
- `deleteTask` - Remove tasks and their subtasks
- `getTaskHierarchy` - View tasks in hierarchical structure
**Memory & Context:**
- `storeMemory` - Save project knowledge, decisions, patterns, and context
- `retrieveMemory` - Search and retrieve relevant memories using semantic or text search
**Workflow Automation:**
- `parsePrompt` - Convert complex requests into structured task workflows
- `executeWorkflow` - Run automated task sequences
- `approveTask` / `rejectTask` - User approval workflow for task execution
- `resumeWorkflow` - Continue paused workflows
- `getWorkflowState` - Check current workflow status
### When to Use Each Tool
**Use `createTask` when:**
- Breaking down complex development work into manageable pieces
- Planning feature implementations or bug fixes
- Creating checklist items for code reviews or deployments
- Setting up project milestones with time estimates
**Use `storeMemory` when:**
- Documenting important architectural decisions
- Saving useful code patterns or configurations
- Recording project-specific conventions or standards
- Storing context about APIs, databases, or external services
- Remembering user preferences or project requirements
**Use `retrieveMemory` when:**
- Looking for relevant past decisions or patterns
- Searching for project-specific information
- Finding examples of similar implementations
- Recalling project conventions or standards
**Use workflow tools when:**
- User requests complex multi-step tasks
- Planning and executing feature development
- Managing deployment or setup procedures
- Coordinating multiple related tasks
### Best Practices
1. **Hierarchical Task Organization:**
```
Main Feature Implementation (parent)
├── API Endpoint Creation (child)
├── Database Schema Updates (child)
└── Frontend Components (child)
├── Component Logic (grandchild)
└── Styling & Layout (grandchild)
```
2. **Memory Organization:**
- Use consistent key naming (e.g., `api_auth_pattern`, `db_connection_config`)
- Include relevant metadata (type, component, date, author)
- Store both decisions AND rationale
3. **Workflow Integration:**
- Parse complex requests into approved task lists first
- Let users review and modify tasks before execution
- Use checkpoints for long-running workflows
### Example Usage Patterns
**Project Setup:**
```
User: "Set up a new React project with TypeScript, testing, and CI/CD"
1. Use parsePrompt to break this into structured tasks
2. Store project requirements and decisions in memory
3. Execute approved tasks step by step
4. Store useful patterns for future projects
```
**Feature Development:**
```
User: "Add user authentication with JWT tokens"
1. Create hierarchical tasks for the feature
2. Retrieve relevant authentication patterns from memory
3. Store new patterns and decisions as you work
4. Update task status as work progresses
```
**Code Review & Documentation:**
```
User: "Review this API design and suggest improvements"
1. Retrieve similar API patterns from memory
2. Create tasks for any improvements needed
3. Store the final API design decisions
4. Create documentation tasks if needed
```
Always prioritize user productivity and maintain project-specific context through consistent use of the memory system.Option 1: Add to Cursor Rules (.cursorrules file)
Create a .cursorrules file in your project root and include the system prompt above.
Option 2: Use in Chat Copy and paste the system prompt into your conversation with Cursor to activate the taskmaster functionality.
Option 3: Custom Instructions Add portions of this prompt to your Cursor settings under custom instructions for persistent behavior.
// 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,
});// 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);// 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,
});- All data stored locally in project directory
- No external API calls for core functionality
- Vector embeddings computed locally using Sentence Transformers
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:
- Open terminal in your project
- Run
pwdto get the full path - Use that exact path in the configuration
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.
This is normal on some systems where native dependencies can't be installed properly. The server will still work perfectly for:
- ✅ Task management (all features)
- ✅ Memory storage and retrieval (basic text search)
- ✅ Workflow execution (all features)
You'll just lose advanced semantic similarity search, but basic text search still works for memory retrieval.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Built on the Model Context Protocol
- Uses Sentence Transformers for embeddings
- Powered by SQLite for reliable data storage
- GitHub Issues: Report bugs or request features
- Documentation: Check this README and inline code documentation
- Examples: See the
examples/directory for usage patterns