JinDaGe - better-notion-mcp MCP Details

article

README

🚀 Better Notion MCP

专为AI智能体优化的、以Markdown为先的Notion MCP服务器

🚀 快速开始

在使用之前，你需要获取你的Notion令牌：访问 https://www.notion.so/my-integrations → 创建集成 → 复制令牌 → 与集成共享页面。

✨ 主要特性

为何是 “Better” ？

它拥有7个基于大型操作的工具，将Notion的28个以上的REST API端点整合为针对AI智能体优化的复合操作。

与官方Notion MCP服务器对比

| 特性 | Better Notion MCP | 官方Notion MCP | | ---- | ---- | ---- | | 内容格式 | Markdown（人类可读） | 原始JSON块（冗长） | | 操作方式 | 复合操作（一次调用即可创建页面、内容和属性） | 原子操作（需要2次以上单独调用） | | 分页处理 | 自动分页（透明处理） | 手动游标管理 | | 批量操作 | 原生批量支持（一次创建/更新/删除多个项目） | 手动遍历项目 | | 工具架构 | 7个基于大型操作的工具（30多个操作） | 28个以上单独的端点工具 | | 数据库查询 | 智能搜索（自动检测最佳匹配） | 需要手动过滤和排序 | | 令牌效率 | 针对AI上下文优化 | 标准API响应 | | 设置方式 | 简单（仅需NOTION_TOKEN） | OAuth流程或令牌 |

📦 安装指南

NPX（推荐）

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "better-notion": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "NOTION_TOKEN", "n24q02m/better-notion-mcp:latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

📚 详细文档

工具概述

7个大型工具，拥有30多个操作：

复合操作：组合操作（例如，一次调用即可创建页面、内容和属性）
自动分页：透明处理大型数据集
批量操作：高效处理多个项目
智能搜索：在数据库查询中自动检测最佳匹配

限制

支持的块类型（Markdown转换）：

✅ 标题（H1 - H3）、段落、列表（无序列表/有序列表）
✅ 代码块、引用、分隔线
✅ 内联格式（粗体、斜体、代码、删除线、链接）

不支持的块类型：

❌ 表格、折叠块、标注、列
❌ 数据库、嵌入内容、图像、文件
❌ 同步块、模板

从源代码构建

本项目使用 mise 进行工具版本管理。如果你没有安装mise，请参考 mise.jdx.dev。

git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp

mise trust
mise install

pnpm install
pnpm build

uv venv
uv pip install pre-commit
uv run pre-commit install
uv run pre-commit run --all-file

前提条件：mise或Node.js 22+以及pnpm。

可用命令

pnpm dev                    # 运行开发服务器并自动重新加载
pnpm build                  # 构建项目
pnpm test                   # 运行测试
pnpm test:watch             # 以监视模式运行测试
pnpm test:coverage          # 运行测试并生成覆盖率报告
pnpm check                  # 检查格式、 linting和类型（Biome + TypeScript）
pnpm check:fix              # 自动修复格式和linting问题

贡献代码

欢迎贡献代码！请参考 CONTRIBUTING.md 了解：

开发工作流程（通过CI验证）
提交规范（通过git钩子强制执行）
测试和代码质量标准

📄 许可证

本项目采用MIT许可证，请查看 LICENSE 了解详情。

如果你觉得这个仓库有用，请给它点个星！⭐

better-notion-mcp