Your tasks. Your rules. Your agents.
A local-first MCP server that gives AI agents native access to a full TaskWarrior-compatible engine.
No cloud. No binary to install. No lock-in. Just a pip install and your agents are in control.
Ask your agent:
"Add a task to review the API spec"
"What's on my plate for today?"
"Run my weekly review"
"Show me the roadmap for Project X"
Most task managers are cloud-first and agent-hostile. TaskMajor is neither.
- 🔒 100% local & private — all data stays on your machine, stored as plain text via the embedded TaskChampion engine
- ⚙️ Full TaskWarrior power — projects, priorities, due dates, tags, UDAs, dependencies, contexts — all accessible by your agent
- 🎭 Profile System — the feature no other task MCP has: define exactly what your agent can see and do, adapted to your methodology
- ⚡ Zero friction — one command installs and starts a fully functional MCP server
pip install taskmajor # or: uv tool install taskmajor
taskmajor # starts at http://localhost:8888Point your MCP client (Claude Desktop, Hermes, Continue, or any MCP-compatible agent) at http://localhost:8888.
That's it. No TaskWarrior binary to install — the engine is embedded.
🤖 Hermes user in a hurry? → 5-minute Hermes setup
Want a specific workflow?
taskmajor --profile standard # task CRUD + agenda (default)
taskmajor --profile productivity # GTD: reviews, energy levels, contexts
taskmajor --profile project-mgmt # sprints, effort tracking, blockers queue→ Full installation options — uv, Docker, from source
Profiles are the heart of TaskMajor. Each profile defines a complete behavioral contract for your agent: what tools it can call, what data structures exist, what views it can read, and how it should reason about your tasks.
| Profile | Extends | What it unlocks |
|---|---|---|
minimal |
— | Bare CRUD: add, query, complete, delete |
standard |
minimal | Agenda views, date tools, metadata, organization prompts |
productivity |
standard | GTD: energy levels (low/medium/high), daily & weekly reviews, capture workflow, context tags (+@) |
project-mgmt |
standard | Sprint planning, effort analytics, blockers queue |
| your-profile | any built-in | Extend any profile without touching the package |
Custom profile in 3 lines:
# ~/.config/myproject/profiles/myprofile/manifest.yaml
extends: [productivity]
# add your own UDAs, contexts, resources, and agent instructionstaskmajor -c ~/.config/myproject→ Profile System documentation
- 🔒 Private by design — plain-text storage, TaskChampion engine, runs entirely on your machine
- 🧠 Profile-shaped agents — agents see only what you expose; switch workflows with one flag
- ⚡ Energy-aware scheduling —
low / medium / highenergy UDA lets your agent suggest tasks that match your current state - 🏷️ Safe context tags —
+@work,+@home,+@focusfilter tasks without breaking TaskWarrior's native context system - 📅 Flexible date expressions — natural language dates resolved before any write operation
- 📋 Daily & weekly reviews — structured review resources and prompts built into the
productivityprofile - 🔄 Optional sync — periodic or manual sync to a TaskChampion server (local or remote)
- 🔌 Any MCP client — works with Claude Desktop, Hermes, Continue, or any MCP-compatible agent
- 🐳 Docker-ready — official Dockerfile for containerized deployments
- 📊 Built-in analytics — stats by project, priority, and status; effort and sprint tracking in
project-mgmt
| For | Start here |
|---|---|
| First install | Getting Started |
| 5-minute walkthrough | Quick Start guide |
| Hermes agent users | Hermes Quick Start |
| Custom workflows | Profile System |
| All profiles reference | Profile Reference |
| Tools & resources API | API Reference |
| Config & CLI flags | Configuration |
| Docker / from source | Deployment |
| Contributing | Contributing |
- Issues & Features: GitHub Issues
- Discussions: GitHub Discussions
MIT — see LICENSE
Built with FastMCP · pytaskwarrior · TaskChampion · Pydantic