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