Notion Workflow MCP Server

notion-workflow-mcp

Personal workflow management via Claude CLI + Notion API, built as an MCP Server.

Inspired by google-keep-mcp — turns Notion into a personal task and knowledge system driven by slash commands.

Features

• 20 MCP tools covering task lifecycle, note-taking, subtask management, and aggregations
• 2 independent Notion databases: 工作流库 (tasks, with project & subtasks) + 笔记库 (notes)
• 12 slash commands: /capture, /subtask, /task_list, /status, /progress, /note, /review, /standup, /overview, /detail, /done, /find
• Project-based task management: tasks belong to projects, with embedded subtasks (priority + status)
• Conversation-to-note: /note auto-summarizes AI conversations into structured notes

Requirements

• Python 3.11+
• uv (recommended) or pip
• Notion account + Integration token

Setup

1. Clone & install

git clone https://github.com/<your-username>/notion-workflow-mcp
cd notion-workflow-mcp
uv venv --python python3.12
uv pip install -e .

2. Configure environment

cp .env.example .env
# Fill in your NOTION_TOKEN, WORKFLOW_DATABASE_ID, NOTES_DATABASE_ID

Getting your IDs:

• NOTION_TOKEN: notion.so/my-integrations → New integration → copy token
• Database IDs: Use the init script to auto-discover them (see step 4)

3. Share databases with your Integration

In Notion: open each database → ... → Connections → select your integration

4. Initialize database schema

python scripts/init_databases.py

This auto-adds all required properties (状态, 优先级, 项目, 截止日期, 标签, 备注) to your existing databases.

5. Register MCP Server with Claude CLI

claude mcp add notion-workflow -- /path/to/.venv/bin/python /path/to/server.py

Or add manually to ~/.claude/settings.json:

{
  "mcpServers": {
    "notion-workflow": {
      "command": "/path/to/notion-workflow-mcp/.venv/bin/python",
      "args": ["/path/to/notion-workflow-mcp/server.py"]
    }
  }
}

Restart Claude CLI — the MCP server loads automatically.

6. Install slash command skills

Slash commands (like /capture, /note, /review) are Claude Code skills defined in .claude/commands/. They need to be accessible from your working directory.

Option A: Work inside this project directory

If you run claude from the notion-workflow-mcp/ directory, skills are automatically available — Claude Code reads .claude/commands/ from the current directory.

Option B: Make skills globally available

To use the slash commands from any directory, copy them to your global Claude Code commands folder:

# Create global commands dir if it doesn't exist
mkdir -p ~/.claude/commands

# Copy all skills
cp notion-workflow-mcp/.claude/commands/*.md ~/.claude/commands/

Option C: Symlink (auto-sync with updates)

mkdir -p ~/.claude/commands
ln -sf $(pwd)/notion-workflow-mcp/.claude/commands/*.md ~/.claude/commands/

After installation, restart Claude CLI. Verify by typing /capture — it should be recognized as a slash command.

7. Install skills

Skills (like decompose-task) are AI-powered workflows in .claude/skills/. Unlike slash commands, skills are auto-discovered by Claude Code from the current directory — no manual registration needed.

Option A: Work inside this project directory

Skills are automatically available when you run claude from notion-workflow-mcp/.

Option B: Make skills globally available

# Copy all skills to global skills directory
cp -r notion-workflow-mcp/.claude/skills/* ~/.claude/skills/

Option C: Symlink (auto-sync with updates)

for dir in notion-workflow-mcp/.claude/skills/*/; do
  ln -sf "$(cd "$dir" && pwd)" ~/.claude/skills/
done

After installation, restart Claude CLI. Skills will appear in the skill list automatically.

Workflow

# 1. Create a task under a project
/capture 重构Notion MCP -p MCP改造 -d 2026-03-28

# 2. Add subtasks
/subtask abc123 去掉关联功能 -pri 高
/subtask abc123 增加项目字段 -pri 紧急
/subtask abc123 创建skill

# 3. View all incomplete tasks
/task_list

# 4. Start working on a subtask
/status abc123 doing 去掉关联功能

# 5. Ask AI a question, then save the answer as a note
> Go 的 context 包怎么用？
> [AI explains...]
/note

# 6. Mark subtask done
/status abc123 done 去掉关联功能

# 7. Update progress
/progress abc123

# 8. End of day review
/review today

# 9. Friday weekly report
/review this week

MCP Tools