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:

1. think like [X] - Sets persona context for all subsequent processing
2. interrogate - Asks clarifying questions
3. rewrite - Rewrites description for clarity
4. estimate - Estimates level of effort and refactoring needs
5. expand - Adds technical detail
6. critique - Provides feedback (with persona if set)
7. user stories - Generates user stories (appended to task description)
8. to-do - Adds to todo list (no implementation)
9. code - Triggers implementation (ONLY tag that writes code)
10. 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:

1. interrogate → Claude asks questions about auth method, session management → Saves as comment
2. expand → Adds technical detail (JWT vs session, password requirements) → Saves as comment
3. user stories → Generates user stories for different auth scenarios → Appends to task description
4. All three tags removed after processing
5. 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:

1. think like → Sets persona: "security engineer"
2. critique → Critiques from security perspective (PCI compliance, data protection) → Saves as comment
3. expand → Expands with security-focused technical details → Saves as comment
4. All tags removed
5. All comments automatically added to Notion task

Example 3: Full Implementation

Notion Task: "Add dark mode toggle" MCP Tags: interrogate, expand, code

What happens:

1. interrogate → Claude asks about implementation approach, storage → Saves as comment
2. expand → Adds technical detail (CSS variables, localStorage, toggle component) → Saves as comment
3. code → Reviews requirements → WRITES THE ACTUAL CODE (creates files, edits components, etc.)
4. All tags removed after processing
5. Feature is fully implemented - not just analyzed

🔧 MCP Capabilities

Tools (4)

Resources (3)

Prompts (6)

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 .env file
• Run from directory containing .env with NOTION_TOKEN and NOTION_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.json is 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

1. Fork and clone
2. pnpm install
3. Create a branch: git checkout -b feat/my-feature
4. Make changes and test
5. Commit: git commit -m "feat: add my feature"
6. Push: git push origin feat/my-feature
7. 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