Better Notion MCP

🚀 Better Notion MCP

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

🚀 快速开始

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

✨ 主要特性

为何是 “Better” ？

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

与官方Notion MCP服务器对比

📦 安装指南

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 了解详情。

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