notion task MCP

概念任务MCP

使用Notion API的Task管理模型上下文协议（MCP）服务器。 AI助手（Claude等）可以直接查看和管理团队的Notion Task DB。

______________________________________________________________________

目录

• 技术堆栈
• 动作方式
• 要求
• 安装
• 设置
• MCP客户端设置
• 交付工具
• Task DB模式
• 开发指南
• 故障射击

______________________________________________________________________

技术堆栈

开发依赖性

______________________________________________________________________

动作方式

┌─────────────────┐     MCP Protocol      ┌─────────────────┐     Notion API     ┌─────────────────┐
│   MCP Client    │ ◄──────────────────► │  Notion Task    │ ◄────────────────► │   Notion DB     │
│ (Claude Desktop │     (stdio/JSON)      │   MCP Server    │     (HTTPS)        │   (Task 관리)    │
│   Claude Code)  │                       │                 │                    │                 │
└─────────────────┘                       └─────────────────┘                    └─────────────────┘

1. MCP客户端 （Claude Desktop、Claude Code等）通过MCP协议向服务器请求工具调用
2. MCP服务器解析请求并通过Notion API操作DB
3. 将结果以JSON格式返回到MCP Client
4. AI助手解释结果并回复用户

MCP（模型上下文协议）란?

Anthropic开发的AI助手和外部工具之间的标准通信协议。 通过该协议，Claude可以安全地与Notion、GitHub、Slack等各种服务进行交互。

______________________________________________________________________

要求

• python：3.11或更高版本
• Notion帐户：Task DB所在的工作空间
• 概念整合：API访问的内部集成
• MCP客户端：Claude Desktop或Claude Code

______________________________________________________________________

安装

1.存储库克隆

git clone 
cd notion_task_mcp

2.创建虚拟环境（建议）

# uv 사용 시 (권장)
uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# 또는 venv 사용 시
python -m venv .venv
source .venv/bin/activate

3.安装软件包

# uv 사용 시 (권장)
uv pip install -e .

# pip 사용 시
pip install -e .

4.确认安装

notion-task-mcp --help
# 또는
python -m notion_task_mcp.server

______________________________________________________________________

设置

1.创建Notion Integration

1. 概念整合 连接页面
2. +新集成 点击
3. 设置：

- 名字: Task MCP （所需名称） - 关联工作空间：选择Task DB所在的工作空间 - 能力: - ✅ 阅读内容 - ✅ 更新内容 - ✅ 插入内容

1. 提交 → 内部整合秘密 复制（稍后使用）

2.确认数据库ID

从Notion打开Task DB页面→从URL提取数据库ID：

https://www.notion.so/workspace/1234567890abcdef1234567890abcdef?v=...
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                      이 부분이 Database ID

3.向Integration授予数据库访问权限

重要信息：如果忽略此步骤，API调用将失败！

1. 在Notion中打开Task DB页面
2. 右上角 ··· 点击
3. 连接 → 连接到 →选择创建的集成

______________________________________________________________________

MCP客户端设置

核心：此处设置Notion API Key和Database ID。

克劳德桌面版

设置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notion-task": {
      "command": "/path/to/.venv/bin/notion-task-mcp",
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "NOTION_DATABASE_ID": "1234567890abcdef1234567890abcdef"
      }
    }
  }
}

提示: command请使用虚拟环境中的可执行文件绝对路径。

克劳德代码

.claude/settings.json 或全局设置（~/.claude/settings.json):

{
  "mcpServers": {
    "notion-task": {
      "command": "notion-task-mcp",
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "NOTION_DATABASE_ID": "1234567890abcdef1234567890abcdef"
      }
    }
  }
}

验证设置

在Claude中测试：

"Notion Task 목록을 보여줘"
"진행 중인 Task가 뭐가 있어?"

______________________________________________________________________

交付工具

“工具”“说明”“主要参数” |------|------|--------------| | get_task |查看Task单件| task_id | | list_tasks |查看Task列表| status, task_type, assignee, priority, labels, services、日期范围等| | create_task 创建Task| title （必需）， task_type, status, priority, assignee, labels 等| | update_task |修改Task| task_id （必需），要修改的字段| | delete_task |删除Task（存档）| task_id | | batch_update_status |批量更改多个Task状态| task_ids, status | | batch_update_assignee |批量更改多个Task联系人| task_ids, assignee |

使用示例

# 조회
"오늘 마감인 Task 목록 보여줘"
"높은 우선순위 Task 중 진행 중인 것들 알려줘"

# 생성
"새 Task 만들어줘: API 문서 작성, 우선순위 높음, 라벨은 문서"

# 수정
"TASK-123 상태를 완료로 변경해줘"

# 일괄 처리
"TASK-001, TASK-002, TASK-003 담당자를 홍길동으로 변경해줘"

______________________________________________________________________

Task DB模式

MCP期待的Notion DB属性：

属性名Notion类型必需说明 |--------|-------------|------|------| |No Unique ID|-|自动生成ID| |标题| Title | Task标题| | 타입 | 选择|-|任务、史诗、问题、项目| 状态状态-待办事宜/正在处理/完成组 |优先级| Select |–低、中、高 负责人Person负责人 创建者Created by--创建者（自动） 开始日期Date--起始日期 结束日期Date-|结束日期| |标签| Multi-select--|分类标签| |服务| Multi-select|-|服务/域| |父项|关系（Self）--|父任务| |子体| Relation（Self）--|子Task |

状态组

할일 (Todo)
├── 보류
└── 시작전

진행 중 (In Progress)
└── 진행중

완료 (Done)
├── 완료
├── 배포됨
└── 보관

______________________________________________________________________

开发指南

设置开发环境

# 개발 의존성 포함 설치
uv pip install -e ".[dev]"

本地测试环境变量（仅限开发人员）

只有在没有MCP客户端的情况下直接运行或测试服务器时才需要：

cp .env.example .env
# .env 파일에 NOTION_API_KEY, NOTION_DATABASE_ID 입력

代码质量检查

# 타입 체크
mypy src

# 린트
ruff check src

# 린트 자동 수정
ruff check --fix src

测试

# 통합 테스트 실행 (실제 Notion API 사용)
# .env 설정 필요
pytest tests/ -v

项目结构

notion_task_mcp/
├── src/notion_task_mcp/
│   ├── __init__.py
│   ├── server.py           # MCP 서버 엔트리포인트
│   ├── notion_client.py    # Notion API 래퍼
│   ├── models.py           # Pydantic 데이터 모델
│   └── tools/
│       ├── __init__.py
│       └── task_tools.py   # MCP Tool 정의
├── tests/
│   └── test_integration.py
├── pyproject.toml
├── .env.example
└── README.md

______________________________________________________________________

故障射击

“需要NOTION_API_KEY”错误

• MCP客户端设置文件的 env 在节中 NOTION_API_KEY验证是否正确输入
• 保存配置文件后重新启动Claude Desktop/Code

“Could not find database”错误

• 验证数据库ID是否正确（从URL中准确提取）
• 验证Integration是否已连接到该数据库

MCP服务器未连接

1. notion-task-mcp 直接在终端上检查命令是否运行
2. 重新启动Claude Desktop/Code
3. 配置文件中的 command 验证路径是否正确

Rate Limit错误

Notion API的平均限制为3 request/sec。 建议在处理大量Task时使用批处理工具。

______________________________________________________________________

______________________________________________________________________

克劳德代码技能（任务技能）

除了MCP服务器之外，Claude Code还提供了 任务技能提供。

快速开始

# 1. Repository 클론
git clone git@github.com:wirobotics/notion_task_mcp.git
cd notion_task_mcp

# 2. 설치 (API Key, DB ID, 사용자 정보 입력)
./install.sh

# 3. Claude Code 재시작 후 사용

使用示例

"진행중인 Task"
"Task 만들어줘"
"WIRB-123 완료"
"내 Project 알려줘"

Skill管理

# 사용자 정보 재설정
~/.claude/skills/task/setup.sh

# 삭제
~/.claude/skills/task/uninstall.sh

有关详细信息，请访问 任务/ 请参考文件夹。

______________________________________________________________________

许可证

MIT许可证