task-master-ai-notion

Task Master - Notion Sync

This project is a fork of eyaltoledano/claude-task-master. It extends the local task management features of Task Master by synchronizing your tasks to Notion, allowing you to leverage Notion's powerful database tools for visualization and management.

Features

• Dump all Task Master tasks into a Notion database.
• Use Notion's Kanban board, timeline, calendar, and other views for your tasks.
• Add rich notes and details to each task page in Notion for enhanced productivity.

Usage

For basic installation and setup, refer to the original documentation.

Additional Setup for Notion Sync

1. Installation

npm installation:

1. Install globally:

   npm install -g task-master-ai-notion

2. Or install locally in your project:

   npm install task-master-ai-notion

3. After installation, use the command:

   task-master-notion init

4. After running task-master-notion init in your project, set the following in your .env file:

   NOTION_TOKEN=...
   NOTION_DATABASE_ID=...

   For details on how to obtain and set these values, see 2. Notion Setup below. Note: This installation provides the task-master-notion command, which can be used alongside the original task-master without conflict.

Local installation:

1. Clone the repo:

   git clone https://github.com/chun92/claude-task-master

2. Install dependencies:

   npm install
   # Run the following only if you want to use the command globally:
   npm link

MCP Setup Example

The following is an example MCP configuration for VS Code (add to .vscode/mcp.json). Important: You must add both NOTION_TOKEN and NOTION_DATABASE_ID to your MCP config for Notion sync to work. For details on how to obtain and set these values, see 2. Notion Setup below. For more detailed MCP setup instructions, please refer to the original documentation.

{
  "servers": {
    "taskmaster-ai-notion": {
      "command": "npx",
      "args": ["-y", "--package=task-master-ai-notion", "task-master-ai-notion"],
      "env": {
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE",
        "NOTION_TOKEN=": "...",
        "NOTION_DATABASE_ID": "..."
      },
      "type": "stdio"
    }
  }
}

2. Notion Setup

1. Create a Notion Integration at Notion Integrations.
   • Set content capabilities: Read content, Update content, Insert content.
   • Use the Internal Integration Secret as your NOTION_TOKEN.
2. Import the Notion template from the Marketplace to your workspace: Claude Task Master Notion Template.
   • On the imported page, set the Integration's Connections (see guide).
   • Set the inline database's ID as NOTION_DATABASE_ID.
     • The database ID can be found in the Notion page URL (e.g., https://www.notion.so/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, use the part before any query string).
     • Important: Use the database ID, not the page ID.

3. Updating for Existing Task Master Users

If you have a tasks.json from version 0.20.0 or later, you can use it directly. (Migration from older versions is not guaranteed.) All updates to tasks in your project will be processed in bulk.

4. Notion Sync

After completing all setup, when you run Task Master commands such as parse-prd, update, analyze-complexity, or set-status to update the state of your tasks, those tasks will be automatically synced to Notion.

Notion Sync Management Commands

For maintaining and troubleshooting your Notion synchronization, the following commands are available:

Validate Notion Sync

task-master-notion validate-notion-sync

Validates the integrity of your Notion synchronization by:

• Checking for orphaned pages in Notion
• Identifying local tasks without corresponding Notion pages
• Detecting synchronization inconsistencies
• Providing detailed diagnostic reports

Repair Notion Sync

task-master-notion repair-notion-db [options]

Repairs synchronization issues and manages duplicate pages:

• --preserve-extra-tasks: Keep tasks you've created manually in Notion while still syncing with TaskMaster
• Removes orphaned pages and duplicate entries
• Fixes mapping inconsistencies between local tasks and Notion pages
• Provides comprehensive repair reports

Reset Notion Database

task-master-notion reset-notion-db

Completely resets your Notion database:

• ⚠️ Warning: This will delete all pages in your Notion database
• Useful for starting fresh or resolving complex synchronization issues
• Requires confirmation before proceeding
• All local tasks will be re-synced to Notion after reset

VS Code Extension Installation

In addition to the command-line interface and MCP integration, Task Master Notion now includes a VS Code Extension that provides a visual Kanban board interface with full Notion synchronization support.

Installation Steps

Option 1: Install Pre-built VSIX (Recommended)

1. Download the Extension:

   • Download the latest VSIX file from the releases page
   • Or build locally (see Option 2 below)

2. Install via VS Code:

   # Method 1: Command line
   code --install-extension path/to/task-master-notion-extension-0.23.0.vsix
   
   # Method 2: VS Code UI
   # 1. Open VS Code
   # 2. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
   # 3. Type "Extensions: Install from VSIX..."
   # 4. Select the downloaded VSIX file

3. Configure Extension Settings:

   • Open VS Code Settings (Ctrl+,)
   • Search for "taskmaster"
   • Ensure the following settings are configured:

     {
       "taskmaster.mcp.command": "task-master-notion-mcp",
       "taskmaster.mcp.args": [],
       "taskmaster.mcp.env": {
         "NOTION_TOKEN": "your_notion_token_here",
         "NOTION_DATABASE_ID": "your_database_id_here",
         "ANTHROPIC_API_KEY": "your_api_key_here"
       }
     }

Option 2: Build from Source

1. Clone and Build:

   git clone https://github.com/chun92/claude-task-master
   cd claude-task-master/apps/extension
   npm install
   npm run package
   cd vsix-build
   npx vsce package --no-dependencies

2. Install Built Extension:

   code --install-extension task-master-notion-extension-0.23.0.vsix

Features

The VS Code Extension provides:

• 🎯 Kanban Board View: Visual task management with drag-and-drop functionality
• 📋 Task Details Panel: Rich task information with subtasks, dependencies, and notes
• 🔄 Real-time Notion Sync: All changes automatically sync to your Notion database
• 🏷️ Tag Support: Switch between different task contexts
• ⚡ scope-up/scope-down: AI-powered task complexity adjustment
• 📊 Task Status Management: Easy status updates with visual feedback

Usage

1. Open Task Master Panel:

   • Click the TaskMaster icon in the Activity Bar
   • Or use Ctrl+Shift+P → "TaskMaster: Show Board"

2. Manage Tasks Visually:

   • Drag tasks between status columns
   • Click tasks to view/edit details
   • Use AI actions to expand or adjust task complexity

3. Notion Integration:

   • All changes are automatically synced to Notion
   • Create rich task details in Notion that sync back to VS Code
   • Use Notion's database views alongside the VS Code interface

Troubleshooting

• Connection Issues: Check that task-master-notion-mcp command is available in your PATH
• Sync Problems: Verify NOTION_TOKEN and NOTION_DATABASE_ID in extension settings
• Performance: Large task lists (>100 tasks) may experience slower loading

Cautions

• It is recommended to use this tool from the console for complex operations.
• MCP mode is supported and stable with the latest updates.
• The VS Code Extension provides the best visual experience with full Notion sync support.
• task-master-notion shares the same tasks.json file as the original task-master and can be used together, but for stability, it is recommended to use only one tool at a time. If you use your existing tasks.json from task-master with task-master-notion, it is strongly recommended to make a backup just in case. The author is not responsible for any loss or corruption of your original file.

Known Bugs (Current Version)

• MCP may create duplicate tasks or use legacy formats unpredictably in multi-tag environments.
• MCP may expand tasks in wrong way with multi-tag environments.

Version Support

Original Version	Notion Sync Support
v.0.24.0	Supported
v.0.23.0	Supported
v.0.22.0	Supported
v.0.21.0	Supported
v.0.20.0	Supported
Earlier versions	Not supported

This fork will continue to track and update for versions after v0.20.0

License

Task Master is licensed under the MIT License with Commons Clause. See the LICENSE file for details.

Original Authors & Contributors

• @eyaltoledano
• @RalphEcom
• @jasonzhou1993
• See contributors