内容
# NotionMCP - 全面的 Notion 知识管理协调器
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置，故障排除
**FastMCP 3.1.0 实现，具有奥地利效率**
**状态：生产就绪（SOTA 2026）** - 高性能 RAG 和语义搜索
**版本：1.2.0** - 真实的评论 API，LLM 驱动的 AI 摘要，工作器管理，Webhook
NotionMCP 是一个强大的 MCP（模型上下文协议）服务器和 Web 应用程序，用于全面管理 Notion 工作区和语义知识检索。具有奥地利效率构建，用于学术研究，项目组织和 RAG 驱动的智能。
> [!IMPORTANT]
> **FastMCP 3.1.0 对齐**：此存储库完全符合 2026 年 2 月的舰队标准。
## 快速开始
```powershell
git clone https://github.com/sandraschi/notion-mcp
cd notion-mcp
just
```
这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 安装依赖项，然后运行 `just serve` 或 `just dev` 启动。
### 手动设置
如果您没有安装 `just`：
## 概述
NotionMCP 提供了 **32 个全面的工具** 用于管理 Notion 工作区和执行语义发现。它具有使用 LanceDB 的本地 RAG 管道，用于私有，高性能的知识检索，以及通过 `ntn` CLI 进行的 Notion 工作器管理。
### 关键 SOTA 功能
- **神经智能（RAG）**：内置 LanceDB 矢量核心，用于语义搜索和上下文感知聊天
- **SOTA 仪表板**：具有实时 Notion 遥测和 LLM “glom on” 发现的功能性 Web 界面
- **完整的页面管理**：创建，更新，搜索和组织页面，支持德语/日语字符
- **语义搜索**：在整个工作区中使用含义和意图发现知识
- **真实评论 API**：通过 Notion 的原生评论 API 进行线程讨论（不再需要呼叫块解决方法）
- **LLM 驱动的摘要**：通过可配置的 OpenAI 兼容 API（Ollama，OpenAI，LM Studio）进行 AI 内容分析
- **工作器管理**：通过 `ntn` CLI 桥部署和管理 Notion 工作器
- **Webhook 事件接收器**：在您的端点接收实时 Notion 通知
- **个人访问令牌（PAT）**：使用用户范围的令牌以及内部集成
- **Markdown 内容端点**：读写页面为增强的 Markdown
- **奥地利可靠性**：零次失败，严格的速率限制意识和欧洲/维也纳上下文
## 快速开始（5 分钟）
### 先决条件
- Python 3.11+
- 具有集成令牌的 Notion 帐户
- 具有 MCP 支持的 Claude Desktop Pro（或具有 MCP 的 Cursor）
- FastMCP 3.1.0+
## 安装
### 先决条件
- [uv](https://docs.astral.sh/uv/) 已安装（推荐）
- Python 3.12+
### 快速开始
使用 `uvx` 立即运行：
```bash
uvx notion-mcp
```
### 克劳德桌面集成
添加到您的 `claude_desktop_config.json`：
```json
"mcpServers": {
"notion-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/notion-mcp", "run", "notion-mcp"]
}
}
```
### 获取您的 Notion 令牌
1. 前往 [https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)
2. 点击“新建集成”
3. 命名为“NotionMCP”并复制令牌
4. 将集成添加到您的工作区
5. 在 `.env` 文件中粘贴令牌
## 工具参考（32 个工具）
### 页面管理（5 个工具）
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `create_page` | 创建具有内容和属性的页面 | 研究笔记，项目文档 |
| `update_page` | 更新现有的页面内容/属性 | 状态更新，内容修订 |
| `get_page_content` | 检索完整的页面和块 | 内容分析，备份 |
| `search_pages` | 跨工作区的自然语言搜索 | 按主题查找研究 |
| `archive_page` | 安全地存档或删除页面 | 项目清理，组织 |
### 数据库操作（6 个工具）
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `create_database` | 创建具有自定义模式的数据库 | 动漫跟踪器，研究数据库 |
| `query_database` | 复杂的过滤和排序 | 查找未完成的任务 |
| `create_database_entry` | 添加具有所有属性类型的条目 | 添加新的动漫，研究论文 |
| `update_database_entry` | 更新现有的条目 | 标记完成，更新评分 |
| `get_database_schema` | 分析数据库结构 | 模式规划，验证 |
| `bulk_import_data` | 有效地导入 CSV/JSON 数据 | 研究数据迁移 |
### 协作（3 个工具）
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `add_comment` | 添加评论到页面/块 | 学术反馈，讨论 |
| `get_comments` | 检索评论线程 | 审查反馈，对话 |
| `get_workspace_users` | 列出工作区用户和权限 | 团队管理，访问控制 |
### 神经发现（RAG）（3 个工具） [新]
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `sync_rag_index` | 将 Notion 工作区与本地 LanceDB 矢量存储同步 | RAG 核心初始化 |
| `search_notion_knowledge` | 使用嵌入式跨索引 Notion 页面进行语义搜索 | 上下文感知研究发现 |
| `clear_rag_index` | 安全地清除本地矢量数据库 | 安全清理，重新索引 |
### 高级功能（4 个工具）
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `setup_automation` | 创建工作流自动化 | 自动通知，触发器 |
| `sync_external_data` | 从外部源同步 | GitHub 仓库，研究 API |
| `generate_ai_summary` | AI 驱动的内容分析 | 研究摘要，见解 |
| `export_workspace_data` | 备份和导出功能 | 数据备份，迁移 |
| `import_workspace_data` | 将 Markdown/JSON 导入 Notion | 大量内容导入 |
### Webhook 管理（2 个工具） [新]
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `verify_webhook` | 存储来自 Notion Webhook POST 的验证令牌 | 完成 Webhook 设置 |
| `list_webhook_events` | 列出接收的 Notion Webhook 事件 | 监控工作区活动 |
### Notion 工作器（6 个工具） [新]
| 工具 | 描述 | 示例用法 |
|------|-------------|-------------|
| `deploy_worker` | 通过 ntn CLI 部署 Notion 工作器 | 部署同步或工具工作器 |
| `list_workers` | 列出部署的工作器 | 检查工作器状态 |
| `scaffold_worker` | 搭建新的工作器项目 | 从模板创建工作器 |
| `worker_logs` | 获取工作器日志 | 调试部署的工作器 |
| `check_ntn` | 验证 ntn CLI 安装 | 预飞行检查 |
| `orchestrate_workers` | 多操作工作器编排 | 批量工作器操作 |
## 奥地利效率特征
### 直接沟通
- **没有精神控制**：关于实际失败的清晰错误消息
- **诚实的限制**：关于 Notion API 限制的明确说明
- **可行的反馈**：操作失败时的具体下一步骤
### 预算意识（~100/月）
- **高效的 API 使用**：智能批处理和缓存
- **速率限制尊重**：智能请求模式以避免成本
- **使用情况监控**：跟踪 API 调用并优化性能
### 维也纳背景
- **时区**：正确的欧洲/维也纳日期/时间处理
- **德语支持**：完整的 UTF-8 支持 , , , 在内容中
- **日期格式**：DD.MM.YYYY 奥地利标准
- **学术工作流**：针对研究和知识管理优化
### 萨巴库友好
- **日语支持**：完整的 Unicode 支持 内容
- **动漫跟踪**：预建的动漫/漫画数据库模板
- **语言学习**：词汇和进度跟踪工具
## 配置
### 环境变量
```bash
# Notion 身份验证（选择一个）
NOTION_TOKEN=secret_your_integration_token_here
# 或
NOTION_PAT=ntn_your_personal_access_token_here
# API 版本
NOTION_VERSION=2026-03-11
# 用于 AI 摘要的 LLM（可选）
LLM_API_URL=http://localhost:11434/v1/chat/completions
LLM_API_KEY=ollama
LLM_MODEL=llama3.2
# Webhook 配置（可选）
NOTION_WEBHOOK_URL=https://your-public-endpoint/api/webhooks/notion
# Notion CLI 用于工作器（可选）
NTN_BIN=ntn
# 奥地利上下文（可选）
TIMEZONE=Europe/Vienna
DATE_FORMAT=DD.MM.YYYY
LANGUAGE=de
# 性能（可选）
MAX_RESULTS_PER_PAGE=100
CACHE_DURATION=300
ENABLE_CACHING=true
```
### 学术模板
预配置的数据库模板，用于：
- **研究论文**：作者，引用，状态跟踪
- **项目管理**：任务，截止日期，进度
- **书目**：具有多种格式的引用管理
- **笔记组织**：分层知识结构
### 萨巴库模板
即用型数据库，用于：
- **动漫跟踪**：状态，评分，集数，类型
- **漫画收藏**：阅读进度，系列管理
- **日语学习**：词汇，JLPT 等级，练习
- **角色数据库**：收藏，统计，系列连接
## 用例
### 学术研究工作流
```python
# 创建研究数据库
await create_database(
title="机器学习研究",
parent_id="page_id",
properties_schema={
"Title": "title",
"Authors": "multi_select",
"Year": "number",
"Status": {"type": "select", "options": ["Reading", "Read", "Cited"]},
"Rating": "number",
"Notes": "rich_text"
}
)
# 添加研究论文
await create_database_entry(
database_id="db_id",
properties={
"Title": "Attention Is All You Need",
"Authors": ["Vaswani", "Shazeer", "Parmar"],
"Year": 2017,
"Status": "Read",
"Rating": 5
},
content="transformer architecture paper..."
)
# 按状态查询
results = await query_database(
database_id="db_id",
filter={"Status": {"select": {"equals": "Reading"}}},
sorts=[{"property": "Year", "direction": "descending"}]
)
```
### 动漫跟踪
```python
# 创建动漫数据库
await create_database(
title="动漫收藏 ",
parent_id="page_id",
properties_schema={
"Title": "title",
"Status": {"type": "select", "options": ["Watching", "Completed", "Plan to Watch", "Dropped"]},
"Rating": "number",
"Episodes": "number",
"Genre": "multi_select",
"Studio": "rich_text"
},
icon=""
)
# 添加动漫条目
await create_database_entry(
database_id="anime_db_id",
properties={
"Title": "Attack on Titan",
"Status": "Completed",
"Rating": 9,
"Episodes": 75,
"Genre": ["Action", "Drama", "Fantasy"],
"Studio": "MAPPA"
}
)
```
### AI 驱动的分析
```python
# 生成研究摘要
summary = await generate_ai_summary(
page_id="research_page_id",
summary_type="comprehensive",
length="medium",
focus_areas=["methodology", "results", "implications"]
)
# 导出工作区备份
backup = await export_workspace_data(
scope="workspace",
format="json",
include_metadata=True,
compression=True
)
```
## 测试
```bash
# 运行所有测试
make test
# 或
pytest tests/ -v
# 仅运行单元测试
make test-unit
# 或
pytest tests/ -v -m "not integration and not slow"
# 仅运行集成测试
make test-integration
# 或
pytest tests/ -v -m integration
# 测试覆盖率
make test-coverage
# 或
pytest tests/ --cov=notion --cov-report=html
# 奥地利效率：仅快速单元测试
pytest tests/test_api.py -v
```
## 开发
### 奥地利效率指南
1. **直接沟通**：没有委婉语，清晰的错误消息
2. **预算意识**：优化以适应 ~100/月 AI 工具预算
3. **实际实施**：没有存根，所有功能完全实现
4. **维也纳上下文**：正确的时区和字符编码
5. **学术重点**：研究和知识管理优化
### 开发命令
```bash
# 安装开发依赖
make install-dev
# 运行 linting
make lint
# 或
ruff check server.py notion/ tests/
# 格式化代码
make format
# 或
ruff format server.py notion/ tests/
# 类型检查
make type-check
# 或
mypy server.py notion/ --ignore-missing-imports
# 运行所有检查
make check
```
### 项目结构
```
notionmcp/
config/ # YAML 配置文件
docs/ # 文档
notion_mcp/ # 核心 Notion 模块
client.py # API 客户端（评论 API，markdown 端点）
pages.py # 页面操作
databases.py # 数据库操作
collaboration.py # 评论 & 用户（真实评论 API）
automations.py # AI 摘要，Webhook，自动化
workers.py # Notion 工作器 via ntn CLI（新）
rag/ # LanceDB 矢量 RAG 管道
transport.py # 双 STDIO/HTTP 传输
tests/ # 测试套件
test_api.py # 单元测试
integration_tests.py # 集成测试
server.py # FastMCP 入口点（32 个工具）
```
## 文档
- **[API 参考](docs/API.md)：** 完整的工具文档
- **[配置指南](docs/Configuration.md)：** 设置和自定义
- **[故障排除](docs/Troubleshooting.md)：** 常见问题和解决方案
## 安全
- **令牌安全**：永远不要将令牌提交到 git
- **最小权限**：授予必要的访问范围
- **速率限制**：尊重 Notion API 限制
- **预算监控**：跟踪使用情况以避免意外成本
## 故障排除
### 常见问题
**服务器在 Cursor 中无法启动```
Issue: 服务器在 Cursor IDE 中启动失败
解决方案：
1. 确保 NOTION_TOKEN 在 Cursor MCP 设置中设置
2. 检查 cwd 指向 notion-mcp 目录
3. 验证 Python 3.11+ 在 PATH 中
4. 查看 CURSOR_FIX.md 详细设置说明
```
**身份验证错误```
Error: Notion API 令牌无效或过期
解决方案： 检查 `.env` 文件或 Cursor MCP 设置中的 NOTION_TOKEN
```
**权限被拒绝```
Error: 请求的页面/数据库未找到
解决方案： 将您的集成添加到包含内容的工作区
```
**速率限制```
Error: 速率限制超过
解决方案： 等待 60 秒并重试，检查您的使用模式
```
**导入错误```
Error: ModuleNotFoundError 或导入失败
解决方案：
1. 安装依赖项：uv pip install -r requirements.txt
2. 检查 PYTHONPATH 包括 notion-mcp 目录
3. 验证所有依赖项是否安装：pip list
```
## 提示 奥地利效率
1. **使用模板**：预配置的学术和萨巴库数据库
2. **批量操作**：使用 bulk_import_data 大数据集
3. **智能缓存**：启用缓存以减少 API 调用
4. **维也纳时区**：所有日期自动转换为欧洲格式
5. **德语字符**：完整的 , , , 在内容中支持
6. **预算监控**：跟踪 API 使用情况以保持在限制内
## 工业质量堆栈
该项目遵循 **SOTA 14.1** 高保真真真理工业标准** 代理编排的高保真编排：
- **Python（核心）**： [Ruff](https://astral.sh/ruff) 用于 linting 和格式化。零容忍核心处理程序中的 `print` 语句 (`T201`)。
- **Webapp（UI）**： [Biome](https://biomejs.dev/) 实现毫秒级 linting。严格执行 `noConsoleLog`。
- **协议合规性**：强化 `stdout/stderr` 隔离，确保崩溃抗性 JSON-RPC 通信。
- **自动化**： [Justfile](./justfile) 适用于所有舰队操作 (`just lint`, `just fix`, `just dev`)。
- **安全**：自动审计通过 `bandit` 和 `safety` 进行。
## 许可
具有奥地利背景的 MIT 许可 - 请参阅 LICENSE 文件了解详情。
---
**在维也纳用奥地利效率构建 **
*Sin temor y sin esperanza* - 实际的 Notion 管理，没有炒作。
**适用于：** 学术研究 项目管理 动漫跟踪 知识组织 维也纳工作流
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器