Sync your local Task Master tasks to Notion, enabling powerful Kanban, timeline, and calendar views. Fork of claude-task-master with Notion integration.
npm install task-master-ai-notionsh
npm install -g task-master-ai-notion
`
2. Or install locally in your project:
`sh
npm install task-master-ai-notion
`
3. After installation, use the command:
`sh
task-master-notion init
`
4. After running task-master-notion init in your project, set the following in your .env file:
`env
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:
`sh
git clone https://github.com/chun92/claude-task-master
`
2. Install dependencies:
`sh
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.
`json
{
"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.
!Notion Usage Example
#### 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.
$3
For maintaining and troubleshooting your Notion synchronization, the following commands are available:
#### Validate Notion Sync
`sh
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
`sh
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
`sh
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.
$3
#### 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:
`bash
# 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:
`json
{
"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:
`bash
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:
`bash
code --install-extension task-master-notion-extension-0.23.0.vsix
`
$3
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
$3
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
$3
- 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.