Taskmaster MCP Server
A Simplified Model Context Protocol Server for Task Management
Taskmaster is a simplified MCP server that provides AI agents with straightforward task management. It works with any LLM - no complex thinking required!
🌟 Key Features
Simple 4-Step Workflow
- create_session: Start a new task session
- create_tasklist: Define your tasks
- execute_next: Get next task to work on
- mark_complete: Complete current task
- end_session: Finish when all tasks done
Works with Any LLM
- No Complex Thinking: No six-hat thinking or capability mapping required
- Auto-Assigned Tools: Standard tools (read_file, edit_file, run_terminal_cmd, codebase_search) auto-assigned
- Simple Guidance: Clear, concise instructions that any LLM can follow
- State Management: Full session persistence and task tracking
Streamlined Design
- Minimal Commands: Only 4 essential commands needed
- Clear Progression: Linear workflow that's easy to follow
- Persistent State: Session and task state maintained throughout
- Error Handling: Simple error messages and recovery guidance
🚀 Quick Start
Installation
git clone <repository-url>
cd taskmaster
pip install -r requirements.txt
Running the Server
python server.py
The server starts on http://localhost:8080/mcp by default.
MCP Client Configuration
Cursor IDE
Add to your mcp.json configuration:
{
"servers": {
"taskmaster": {
"url": "http://localhost:8080/mcp",
"transport": "http"
}
}
}
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"taskmaster": {
"url": "http://localhost:8080/mcp",
"transport": "http"
}
}
}
📋 Simple Workflow Guide
1. Create Session
# Start a new task session
taskmaster(
action="create_session",
session_name="My Development Project",
task_description="Build a web application with authentication"
)
2. Create Task List
# Define your tasks
taskmaster(
action="create_tasklist",
tasklist=[
{"description": "Set up project structure"},
{"description": "Implement authentication"},
{"description": "Create user interface"}
]
)
3. Execute Tasks
# Get next task to work on
taskmaster(action="execute_next")
# Complete current task and move to next
taskmaster(action="mark_complete")
# Repeat until all tasks done
4. End Session
# Finish when all tasks complete
taskmaster(action="end_session")
🛠️ Available Actions
Core Workflow Actions
| Action | Purpose | Key Parameters |
|---|---|---|
create_session | Start new task session | session_name, task_description |
create_tasklist | Define your tasks | tasklist |
execute_next | Get next task to work on | - |
mark_complete | Complete current task | - |
end_session | Finish when all tasks done | - |
Utility Actions
| Action | Purpose | Key Parameters |
|---|---|---|
get_status | Check current workflow state | - |
collaboration_request | Request human input/guidance | collaboration_context |
edit_task | Modify existing task | task_id, updated_task_data |
🔧 Architecture & Design
Core Components
- TaskmasterCommandHandler: Routes and processes all taskmaster actions
- SessionManager: Manages workflow sessions with persistent state
- WorkflowStateMachine: Simple state management for task execution
- AsyncSessionPersistence: High-performance file-based state persistence
- Command Handlers: Simple handlers for each action type
Design Principles
- Simplicity First: Easy to understand and use with any LLM
- State Management: Full session and task persistence
- Linear Workflow: Clear progression through tasks
- Minimal Complexity: No complex thinking or mapping required
- Extensible: Easy to add new features if needed
Data Flow
- MCP Client connects via HTTP transport
- Commands routed through TaskmasterCommandHandler
- Simple command handlers process actions
- Session state persisted automatically
- Clear guidance for next steps
⚙️ Configuration
Customize server behavior by editing config.yaml:
state_directory: 'taskmaster/state'
session_backup_count: 5
🚀 Production Deployment
Smithery.ai Deployment
The server is optimized for deployment on Smithery.ai:
- Repository Setup: Ensure all files are committed to GitHub
- Smithery Configuration:
smithery.yamlis pre-configured for container deployment - Automated Deployment: GitHub Actions workflow handles testing and container building
Docker Deployment
docker build -t taskmaster-mcp .
docker run -p 8080:8080 taskmaster-mcp
Environment Variables
PORT: Server port (default: 8080)SMITHERY_DEPLOY: Set to "true" for Smithery deployment mode
🧪 Testing
Running Tests
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=taskmaster --cov-report=html
Test Coverage
The server maintains comprehensive test coverage across:
- Core workflow functionality
- Command handlers and routing
- Session management and persistence
- Error handling scenarios
🤝 Contributing
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
For detailed development information, see the Developer Guide in the docs/ directory.
📜 License
MIT License - see LICENSE file for details.
Taskmaster MCP Server - Intelligent task management for AI agents with production-grade reliability, structured planning methodology, and advanced workflow orchestration.
