task-master-ai-notion
Version:
Sync your local Task Master tasks to Notion, enabling powerful Kanban, timeline, and calendar views. Fork of claude-task-master with Notion integration.
268 lines (212 loc) • 11 kB
Markdown
# Task Master - Notion Sync
This project is a fork of [eyaltoledano/claude-task-master](https://github.com/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](https://github.com/eyaltoledano/claude-task-master?tab=readme-ov-file#documentation).
### Additional Setup for Notion Sync
#### 1. Installation
**npm installation:**
1. Install globally:
```sh
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](#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](#2-notion-setup) below.
For more detailed MCP setup instructions, please refer to the [original documentation](https://github.com/eyaltoledano/claude-task-master?tab=readme-ov-file#option-1-mcp-recommended).
```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](https://www.notion.so/profile/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](https://www.notion.com/ko/templates/claude-task-master).
- On the imported page, set the Integration's Connections ([see guide](https://www.notion.com/help/add-and-manage-connections-with-the-api)).
- 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
```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.
### Installation Steps
#### Option 1: Install Pre-built VSIX (Recommended)
1. **Download the Extension**:
- Download the latest VSIX file from the [releases page](https://github.com/chun92/claude-task-master/releases)
- 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
```
### 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 |
|------------------|--------------------|
| v0.26.0 | Supported |
| v.0.25.0 | Supported |
| 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](LICENSE) file for details.
## Original Authors & Contributors
- [@eyaltoledano](https://x.com/eyaltoledano)
- [@RalphEcom](https://x.com/RalphEcom)
- [@jasonzhou1993](https://x.com/jasonzhou1993)
- See [contributors](https://github.com/eyaltoledano/claude-task-master/graphs/contributors)