SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场easy-notion-mcp-integration

easy-notion-mcp-integration

智能体与模型

查看项目

更新于 10-16 02:13

技能介绍

用途

easy-notion-mcp 是一个生产级的 Model Context Protocol（MCP）服务器，用于在 AI 智能体与 Notion 之间建立桥梁。它的核心设计是让智能体使用 GitHub 风格 Markdown 而非原始 Notion API JSON 来读写 Notion 内容，从而降低智能体处理 Notion 数据的复杂度。项目提供 42 个 MCP 工具，覆盖页面、数据库、搜索、文件和区块操作，并支持 24 种区块类型（包括折叠列表、分栏、标注、表格和文件上传）的双向保真转换。

主要能力

  • Markdown 优先的输入输出：智能体只需处理 Markdown，服务器负责所有 Notion 区块 JSON 的转换。
  • 数据库易用性：可写入简洁的属性对象（如 { "Status": "Done" }），服务器自动完成 schema 映射。
  • 双传输方式：支持 Stdio（API Token）或 HTTP（OAuth/Bearer Token）。
  • 可选 Redis：用于多实例部署时的共享 schema 缓存与 OAuth 持久化。
  • 安全默认值：内容净化、URL 校验、工作区根目录文件限制。

使用方式

安装

推荐使用 npx 快速启动，在 MCP 客户端（如 Claude Desktop、Cursor 等）中配置：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "easy-notion-mcp"],
      "env": {
        "NOTION_TOKEN": "YOUR_NOTION_INTEGRATION_TOKEN"
      }
    }
  }
}

从源码安装：

git clone https://github.com/Grey-Iris/easy-notion-mcp.git
cd easy-notion-mcp
npm install
npm run build

MCP 客户端配置：

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/easy-notion-mcp/dist/index.js"],
      "env": {
        "NOTION_TOKEN": "YOUR_NOTION_INTEGRATION_TOKEN",
        "NOTION_ROOT_PAGE_ID": "optional_default_parent_page_id"
      }
    }
  }
}

获取 Notion Integration Token

  1. 访问 https://www.notion.so/my-integrations
  2. 点击 + New integration
  3. 命名集成并选择能力
  4. 复制 Internal Integration Token（以 ntn_ 开头）
  5. 将目标页面/数据库共享给你的集成

配置

核心环境变量：

# stdio 传输必需
NOTION_TOKEN=ntn_your_integration_token_here

# 可选：create_page 的默认父页面
NOTION_ROOT_PAGE_ID=abc123def456

# 禁用读取时的内容提示前缀（默认：false）
NOTION_TRUST_CONTENT=false

# file:// 上传的根目录（默认：cwd）
NOTION_MCP_WORKSPACE_ROOT=/path/to/workspace

# 日志级别：debug, info, warn, error（默认：info）
LOG_LEVEL=info

HTTP 传输（OAuth 或静态 Bearer）：

# /mcp 端点的静态 bearer token
NOTION_MCP_BEARER=your_random_secret_token

# OAuth 配置
NOTION_OAUTH_CLIENT_ID=your_oauth_client_id
NOTION_OAUTH_CLIENT_SECRET=your_oauth_client_secret

# HTTP 服务器设置
PORT=3333
NOTION_MCP_BIND_HOST=127.0.0.1

Redis（可选多实例持久化）：

# 启用 Redis（设置 REDIS_URL 时自动启用）
REDIS_ENABLED=true
REDIS_URL=redis://127.0.0.1:6379/0

# 或单独配置：
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0
REDIS_KEY_PREFIX=easy-notion:
REDIS_CONNECT_TIMEOUT_MS=10000
REDIS_MAX_RETRIES=3

.env 文件设置：

cp .env.example .env
# 编辑 .env 填入你的配置

MCP 工具参考

页面操作

  • read_page：以 Markdown 读取 Notion 页面。
  • create_page：用 Markdown 内容创建新页面。
  • update_page：用 Markdown 更新页面内容（mode 可为 replace 或 append）。
  • append_to_page：向已有页面追加 Markdown。
  • delete_page：将页面移入回收站。

数据库操作

  • query_database：带过滤和排序查询数据库。
  • get_database：获取数据库 schema 和属性。
  • add_database_entry：创建数据库条目并自动转换 schema。
  • update_database_entry：更新数据库条目属性或内容。

搜索操作

  • search_notion：跨工作区全文搜索。

文件操作

  • upload_file：上传本地文件到页面（仅 stdio 传输）。
  • add_image：从 URL 向页面添加图片。

区块操作

  • create_block：创建特定区块类型（如 callout、toggle 等）。

CLI 用法

项目包含 CLI，用于低上下文访问 Notion：

# 只读模式
npx easy-notion-mcp --profile readonly

# 读写模式
npx easy-notion-mcp --profile readwrite

# 自定义配置
NOTION_TOKEN=ntn_xxx npx easy-notion-mcp --profile readwrite

开发工作流

# 安装依赖
npm install

# 开发监听模式
npm run dev

# 本地运行 stdio 服务器
NOTION_TOKEN=ntn_xxx npm start

# 运行 HTTP 服务器
NOTION_TOKEN=ntn_xxx NOTION_MCP_BEARER=$(openssl rand -hex 32) npm run start:http

测试：

npm test
npm run test:watch
npm run typecheck
npm run lint
npm run build

集成测试：

cp .env.example .env
# 设置 E2E_ROOT_PAGE_ID 为测试页面
npm run test:e2e

HTTP 传输设置

静态 Bearer Token：

export NOTION_MCP_BEARER=$(openssl rand -hex 32)
NOTION_TOKEN=ntn_xxx NOTION_MCP_BEARER=$NOTION_MCP_BEARER npm run start:http

HTTP 客户端配置：

{
  "mcpServers": {
    "notion-http": {
      "url": "http://127.0.0.1:3333/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_BEARER_TOKEN"
      }
    }
  }
}

OAuth 流程：

NOTION_OAUTH_CLIENT_ID=your_client_id \
NOTION_OAUTH_CLIENT_SECRET=your_client_secret \
npm run start:http

# 访问 http://localhost:3333/auth/login
# 完成 OAuth 流程
# Token 存储在 Redis 或加密文件中

适用场景

  • 让 AI 智能体以 Markdown 方式读写 Notion 页面与数据库。
  • 在 Claude Desktop、Cursor 等 MCP 客户端中集成 Notion 操作。
  • 需要多实例部署并通过 Redis 共享 schema 缓存与 OAuth 持久化的场景。
  • 需要 HTTP 传输与 OAuth/Bearer 认证的远程或服务化部署。
  • 需要文件上传、图片添加、区块创建等丰富内容操作的自动化流程。

限制与注意事项

  • 文件上传（file:// URL）仅支持 stdio 传输，且所有路径必须位于 NOTION_MCP_WORKSPACE_ROOT 内，符号链接会被校验以防止逃逸；HTTP 传输应使用 HTTPS URL。
  • 默认所有读取操作会附带内容提示前缀，警告智能体内容可能不可信；仅在受信任工作区可设置 NOTION_TRUST_CONTENT=true 禁用。
  • 属性名称区分大小写，遇到未知属性名错误时应先调用 get_database 获取当前 schema。
  • schema 缓存 TTL 未直接提供配置项，需在代码中调整（src/persistence/cache-store.ts 中 DEFAULT_TTL = 3600）。
  • Redis 连接警告需启动 Redis 或显式禁用（REDIS_ENABLED=false）。
  • 401 invalid_token（HTTP 模式）需确认客户端与服务端 bearer token 一致。
  • 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。