taskflow-mcp
AI-powered Notion task workflow automation for Claude Code
taskflow-mcp is a Model Context Protocol (MCP) server that automates Notion task workflows with AI-powered tag processing. Simply add MCP tags to your Notion tasks, and Claude Code will intelligently interrogate, expand, critique, rewrite, and even implement them.
🎯 Features
Full MCP Implementation
- 4 Tools - Direct task processing, querying, and updates
- 3 Resources - Quick access to Ready, In Progress, and all tagged tasks
- 6 Prompts - AI-powered workflows (interrogate, expand, critique, user stories, rewrite, prepare for coding)
- Sampling - LLM-powered analysis integrated via prompts
Intelligent Tag Processing
- Priority-based - Tags processed in optimal order automatically
- Persona support - "think like X" tags add expert context to all analysis
- Automatic tag removal - Tags cleared after successful processing
- Dry-run mode - Preview what would happen without making changes
AI-Powered Workflows (with Automatic Actions)
- interrogate - Claude asks clarifying questions → Saves as comment
- expand - Adds technical detail, APIs, edge cases → Saves as comment
- rewrite - Rewrites task for clarity → Updates task description
- estimate - Estimates effort and refactoring → Saves as comment
- critique - Provides constructive feedback → Saves as comment
- user stories - Generates user stories → Appends to description
- to-do - Adds to todo list → No code written
- code - Actually implements the feature (WRITES CODE)
- confirm - Verifies implementation complete → Saves verification as comment
🚀 Quick Start
1. Install
git clone https://github.com/themightyboosh/taskflow-mcp.git
cd taskflow-mcp
pnpm install
2. Configure
Create .env file in your project directory:
NOTION_TOKEN=ntn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NOTION_DATABASE_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Get your Notion token: https://www.notion.so/my-integrations
3. Setup Claude Code
Add to your .mcp.json (or Claude Code config):
{
"mcpServers": {
"taskflow-mcp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/taskflow-mcp/packages/mcp/index.js"]
}
}
}
4. Add MCP Tags in Notion
Add a multi-select property called "MCP" to your Notion database, then tag tasks with:
- think like [persona] - e.g., "think like a security engineer"
- interrogate - Claude asks clarifying questions
- expand - Add technical detail
- rewrite - Rewrite for clarity
- critique - Get constructive feedback
- user stories - Generate user stories
- to-do - Add to todo list only
- code - Implement the task automatically
5. Use in Claude Code
Via Resources:
Show me notion://tasks/ready
Via Tools:
Process all my Notion tasks
Via Prompts:
Interrogate task [task-id]
📖 Documentation
- SETUP.md - Detailed setup guide
- MCP_CAPABILITIES.md - Full MCP capability reference
🏗️ Architecture
taskflow-mcp/
├── packages/mcp/
│ ├── index.js # Main MCP server
│ ├── notion-client.js # Notion API wrapper
│ ├── utils/
│ │ ├── config-loader.js # Per-project .env loading
│ │ ├── tag-manager.js # Tag priority & processing
│ │ └── image-downloader.js # Image download for vision
├── .env.example
├── .mcp.json.example
└── README.md
🎨 Tag Processing Order
Tags are processed in this priority order:
- think like [X] - Sets persona context for all subsequent processing
- interrogate - Asks clarifying questions
- rewrite - Rewrites description for clarity
- estimate - Estimates level of effort and refactoring needs
- expand - Adds technical detail
- critique - Provides feedback (with persona if set)
- user stories - Generates user stories (appended to task description)
- to-do - Adds to todo list (no implementation)
- code - Triggers implementation (ONLY tag that writes code)
- confirm - Verifies implementation is complete
Each tag is removed after successful processing.
💡 Usage Examples
Example 1: Requirements Gathering
Notion Task: "Add user authentication"
MCP Tags: interrogate, expand, user stories
What happens:
- interrogate → Claude asks questions about auth method, session management → Saves as comment
- expand → Adds technical detail (JWT vs session, password requirements) → Saves as comment
- user stories → Generates user stories for different auth scenarios → Appends to task description
- All three tags removed after processing
- All actions performed automatically - no manual intervention needed
Example 2: Expert Review
Notion Task: "Implement payment processing"
MCP Tags: think like a security engineer, critique, expand
What happens:
- think like → Sets persona: "security engineer"
- critique → Critiques from security perspective (PCI compliance, data protection) → Saves as comment
- expand → Expands with security-focused technical details → Saves as comment
- All tags removed
- All comments automatically added to Notion task
Example 3: Full Implementation
Notion Task: "Add dark mode toggle"
MCP Tags: interrogate, expand, code
What happens:
- interrogate → Claude asks about implementation approach, storage → Saves as comment
- expand → Adds technical detail (CSS variables, localStorage, toggle component) → Saves as comment
- code → Reviews requirements → WRITES THE ACTUAL CODE (creates files, edits components, etc.)
- All tags removed after processing
- Feature is fully implemented - not just analyzed
🔧 MCP Capabilities
Tools (4)
| Tool | Description |
|---|---|
process_tasks | Process all tasks with MCP tags |
query_tasks | Query tasks by status or MCP tags |
add_comment | Add comment to Notion task |
update_task | Update task properties |
Resources (3)
| Resource | Description |
|---|---|
notion://tasks/ready | Ready tasks with MCP tags |
notion://tasks/in-progress | In Progress tasks with MCP tags |
notion://tasks/with-mcp-tags | All tasks with MCP tags |
Prompts (6)
| Prompt | Description |
|---|---|
interrogate_task | Ask clarifying questions |
expand_task | Add technical detail |
critique_task | Provide constructive feedback |
generate_user_stories | Generate user stories |
rewrite_task | Rewrite for clarity |
prepare_for_coding | Analyze and implement |
See MCP_CAPABILITIES.md for full details.
🛠️ Development
# Install dependencies
pnpm install
# Start MCP server (for testing)
pnpm start
# Development mode (auto-reload)
pnpm dev
🐛 Troubleshooting
"No .env file found"
- taskflow-mcp requires per-project
.envfile - Run from directory containing
.envwithNOTION_TOKENandNOTION_DATABASE_ID
"Property MCP does not exist"
- Add a multi-select property called "MCP" to your Notion database
- Configure your Notion integration to have access to the database
MCP server not connecting
- Verify absolute path in
.mcp.jsonis correct - Ensure Node.js 20+ is installed
- Check Notion token is valid
- Restart Claude Code after config changes
📝 Requirements
- Node.js 20+
- pnpm 10+ (or npm)
- Notion integration with database access
- Claude Code with MCP support
🤝 Contributing
Contributions welcome! Please open an issue or PR.
Development Setup
- Fork and clone
pnpm install- Create a branch:
git checkout -b feat/my-feature - Make changes and test
- Commit:
git commit -m "feat: add my feature" - Push:
git push origin feat/my-feature - Open a PR
📧 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
📜 License
MIT © Monumental
🎯 Roadmap
- Multiple database support
- Custom tag definitions via config
- Background polling mode (watch for new tags)
- Webhook support for real-time processing
- Analytics dashboard
- Slack/Discord notifications
- Task templates
- Batch operations
Made with ❤️ by Monumental