Notion MCP

官方

官方Notion MCP服务器，用于AI代理搜索、读取、创建和更新Notion页面、数据库及工作区内容。

GitHub

4.5k

你可以用 Notion MCP 做什么？

按标题搜索页面或数据源 — 使用 post-search 按名称查找工作区中的页面和数据源。
以 Markdown 格式读取页面内容 — 使用 retrieve-page-markdown 检索页面的完整内容，可选择包含会议记录。
使用 Markdown 编辑页面内容 — 使用 update-page-markdown 覆盖或查找并替换页面内容。
使用筛选和排序查询数据源 — 通过 query-data-source 对数据源运行结构化查询。
在父页面或数据源内创建新页面 — 使用 post-page 添加页面，指定 page_id 或 database_id 作为父级。
将页面移动到不同的父位置 — 使用 move-page 移动页面以重新组织工作区。

文档

Notion MCP 服务器

[!NOTE]

我们推出了 Notion MCP，一个远程 MCP 服务器，具有以下改进：

通过标准 OAuth 轻松安装。无需再手动配置 JSON 或 API 令牌。

为 AI 代理量身定制的强大工具，包括以 Markdown 格式编辑页面。这些工具在设计时充分考虑了优化令牌消耗。

了解更多并开始使用，请访问 Notion MCP 文档。

我们正在优先考虑并仅积极支持 Notion MCP（远程）。因此：

我们未来可能会停用此本地 MCP 服务器仓库。

此处的议题和拉取请求不会被积极监控。

请不要在此处提交与远程 MCP 相关的议题；请改为联系 Notion 支持。

notion-mcp-sm

本项目为 Notion API 实现了一个 MCP 服务器。

mcp-demo

⚠️ 版本 2.0.0 重大变更

版本 2.0.0 迁移至 Notion API 2025-09-03，该版本引入了数据源作为数据库的主要抽象。

变更内容

移除的工具（3 个）：

post-database-query - 替换为 query-data-source
update-a-database - 替换为 update-a-data-source
create-a-database - 替换为 create-a-data-source

新增的工具（7 个）：

query-data-source - 使用过滤器和排序查询数据源（数据库）
retrieve-a-data-source - 获取数据源的元数据和模式
update-a-data-source - 更新数据源属性
create-a-data-source - 创建新的数据源
list-data-source-templates - 列出数据源中的可用模板
move-page - 将页面移动到不同的父级位置
retrieve-a-database - 获取数据库元数据，包括其数据源 ID

参数变更：

所有数据库操作现在使用 data_source_id 而非 database_id
搜索过滤值从 ["page", "database"] 更改为 ["page", "data_source"]
页面创建现在支持 page_id 和 database_id 父级（用于数据源）

我需要迁移吗？

无需更改代码。 MCP 工具在服务器启动时自动发现。当您升级到 v2.0.0 时，AI 客户端将自动看到新的工具名称和参数。旧的数据库工具不再可用。

如果您有硬编码的工具名称或引用了旧数据库工具的提示，请更新它们以使用新的数据源工具：

旧工具 (v1.x)	新工具 (v2.0)	参数变更
`post-database-query`	`query-data-source`	`database_id` → `data_source_id`
`update-a-database`	`update-a-data-source`	`database_id` → `data_source_id`
`create-a-database`	`create-a-data-source`	无变更（使用 `parent.page_id`）

注意： retrieve-a-database 仍然可用，并返回数据库元数据，包括数据源 ID 列表。使用 retrieve-a-data-source 获取特定数据源的模式和属性。

现在工具总数：22 个（v1.x 中为 19 个）

页面内容作为 Markdown

服务器公开了两个工具，用于将页面内容作为增强的 Markdown 而非块 JSON 处理，这对 AI 代理来说显著提高了令牌效率：

retrieve-page-markdown — 以 Markdown 格式读取页面的完整内容（GET /v1/pages/{page_id}/markdown）。传递 include_transcript: true 以内联会议记录转录。
update-page-markdown — 使用 Markdown 编辑页面内容（PATCH /v1/pages/{page_id}/markdown）。优先使用 replace_content 覆盖整个页面，或使用 update_content 进行有针对性的查找和替换编辑。

这些端点需要 Notion API 版本 2026-03-11。服务器现在从 OpenAPI 规范中按操作获取 Notion-Version 标头，因此这些工具使用 2026-03-11，而 API 的其余部分继续使用 2025-09-03 — 无需配置。如果您通过 OPENAPI_MCP_HEADERS 自行设置了 Notion-Version，您的值将对每个工具优先使用。

安装

1. 在 Notion 中设置集成

前往 https://www.notion.so/profile/integrations 并创建一个新的内部集成或选择一个现有的集成。

Creating a Notion Integration token

虽然我们限制了 Notion API 的公开范围（例如，您将无法通过 MCP 删除数据库），但将工作区数据暴露给 LLM 存在非零风险。注重安全的用户可能希望进一步配置集成的_功能_。

例如，您可以通过仅从“配置”选项卡授予“读取内容”访问权限来创建只读集成令牌：

Notion Integration Token Capabilities showing Read content checked

2. 将内容连接到集成

确保相关页面和数据库已连接到您的集成。

为此，请访问内部集成设置中的访问选项卡。编辑访问权限并选择您要使用的页面。

Integration Access tab

Edit integration access

或者，您可以单独授予页面访问权限。您需要访问目标页面，点击 3 个点，然后选择“连接到集成”。

Adding Integration Token to Notion Connections

3. 将 MCP 配置添加到您的客户端

使用 npm

Cursor 和 Claude

将以下内容添加到您的 .cursor/mcp.json 或 claude_desktop_config.json（MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json）

选项 1：使用 NOTION_TOKEN（推荐）

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

选项 2：使用 OPENAPI_MCP_HEADERS（用于高级用例）

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

Zed

将以下内容添加到您的 settings.json

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

使用 Copilot CLI 交互式添加 MCP 服务器：

/mcp add

或者，创建或编辑配置文件 ~/.copilot/mcp-config.json 并添加：

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

有关更多信息，请参阅 Copilot CLI 文档。

使用 Docker

使用 Docker 运行 MCP 服务器有两种选项：

选项 1：使用官方 Docker Hub 镜像

将以下内容添加到您的 .cursor/mcp.json 或 claude_desktop_config.json

使用 NOTION_TOKEN（推荐）：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

使用 OPENAPI_MCP_HEADERS（用于高级用例）：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "mcp/notion"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

此方法：

使用官方 Docker Hub 镜像
通过环境变量正确处理 JSON 转义
提供更可靠的配置方法

选项 2：本地构建 Docker 镜像

您也可以在本地构建并运行 Docker 镜像。首先，构建 Docker 镜像：

docker compose build

然后，将以下内容添加到您的 .cursor/mcp.json 或 claude_desktop_config.json

使用 NOTION_TOKEN（推荐）：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

使用 OPENAPI_MCP_HEADERS（用于高级用例）：

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
        "notion-mcp-server"
      ]
    }
  }
}

不要忘记将 ntn_**** 替换为您的集成密钥。从您的集成配置选项卡中找到它：

Copying your Integration token from the Configuration tab in the developer portal

传输选项

Notion MCP 服务器支持两种传输模式：

STDIO 传输（默认）

默认传输模式使用标准输入/输出进行通信。这是大多数客户端（如 Claude Desktop）使用的标准 MCP 传输。

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio

可流式 HTTP 传输

对于基于 Web 的应用程序或偏好 HTTP 通信的客户端，您可以使用可流式 HTTP 传输：

# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

使用可流式 HTTP 传输时，服务器默认将在 http://127.0.0.1:<port>/mcp 上可用。

身份验证

可流式 HTTP 传输需要 Bearer 令牌身份验证以确保安全。您有三个选项：

选项 1：自动生成的令牌（仅用于开发）

npx @notionhq/notion-mcp-server --transport http

服务器将生成一个安全的随机令牌，并将其写入具有受限权限的文件：

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

选项 2：通过命令行自定义令牌（推荐用于生产）

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

选项 3：通过环境变量自定义令牌（推荐用于生产）

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

如果同时提供，命令行参数 --auth-token 优先于 AUTH_TOKEN 环境变量。

不安全选项：禁用 HTTP 身份验证

您只能通过显式的不安全标志禁用 Bearer 令牌身份验证：

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

警告：--unsafe-disable-auth 是不安全的。服务器可能通过 DNS 重新绑定对您访问的页面可达。仅在隔离网络上使用。

当身份验证被禁用时，服务器通过检查 Host 和 Origin 标头是否与配置的本地主机和环回主机匹配来启用 DNS 重新绑定保护。之前的 --disable-auth 标志仍作为已弃用的别名被接受，但会打印警告。

发出 HTTP 请求

所有对可流式 HTTP 传输的请求必须在 Authorization 标头中包含 Bearer 令牌：

# Example request
curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

注意： 在使用任一传输模式时，请确保设置 NOTION_TOKEN 环境变量（推荐）或 OPENAPI_MCP_HEADERS 环境变量为您的 Notion 集成令牌。

服务多个集成（按请求令牌透传）

默认情况下，服务器在启动时使用单个令牌向 Notion 进行身份验证，这将一个部署锁定到一个 Notion 集成。为了让单个部署服务多个集成，启用令牌透传，以便每个客户端在每个连接中提供自己的 Notion 集成令牌：

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

然后，客户端在初始化请求中使用专用的 Notion-Token 标头发送其 Notion 令牌：

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

每个连接的令牌解析顺序如下：

Notion-Token 标头（首选 — 明确，并且与服务器自身的 Authorization 网关身份验证兼容）。如果存在，它必须是有效的 Notion 令牌，否则请求将被拒绝并返回 401。
Authorization: Bearer ntn_**** — 仅当服务器自身的 Bearer 身份验证关闭时（--unsafe-disable-auth），该标头才能直接携带 Notion 令牌。
否则，使用启动时的环境令牌（NOTION_TOKEN / OPENAPI_MCP_HEADERS）（如果已设置），这样透传和默认集成可以在一个部署上共存。

注意：

只有带有 Notion 令牌前缀（ntn_、旧版 secret_）的值才会被视为 Notion 令牌，因此服务器的网关密钥和租户的 Notion 令牌永远不会冲突。
每个令牌都绑定到其 MCP 会话；令牌永远不会被记录（仅发出经过编辑的前缀）。
这是一个刻意的令牌透传设置。始终通过 TLS 部署，并优先保持服务器自身的 Bearer 身份验证（--auth-token）作为多租户流量前的网关启用。

示例

使用以下指令

Comment "Hello MCP" on page "Getting started"

AI 将正确规划两个 API 调用，v1/search 和 v1/comments，以完成任务

类似地，以下指令将导致一个名为“Notion MCP”的新页面添加到父页面“Development”中

Add a page titled "Notion MCP" to page "Development"

您也可以直接引用内容 ID

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

开发

构建和测试

npm run build
npm test

执行

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

在 Cursor 中本地测试更改：

从仓库根目录运行 npm link 命令，为 notion-mcp-server 包创建机器全局符号链接。
将下面的配置片段合并到 Cursor 的 mcp.json（或您要测试的其他 MCP 客户端）中。
（清理）从仓库根目录运行 npm unlink。

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

发布

npm login
npm publish --access public