Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Notion MCP 服务器

[!NOTE]

为获得最佳体验，请使用 远程 Notion MCP， 这是我们官方托管的 MCP 服务器。本仓库是一个独立的、自托管的 MCP 服务器实现，已不再积极维护或支持。请改用远程 Notion MCP。 它是为 让 AI 代理获得更快的结果并消耗更少的令牌而专门构建的。

远程 Notion MCP 可以语义化搜索你的工作区和已连接的应用，以 Markdown 格式 读取和编辑页面，并且只返回最相关的上下文。这意味着更少的等待时间、 更少的上下文窗口占用，以及更低的令牌成本。它还使用 OAuth， 并自动尊重每个用户现有的 Notion 权限——无需 API 令牌、JSON 配置、 手动页面共享或维护本地服务器。

功能	远程 Notion MCP	本项目（本地）
快速、托管的体验	✅	本地运行和更新
令牌高效的响应	✅	有限
为 AI 代理量身定制的强大工具	✅	基于 API 的基础工具
跨 Notion 工作区的语义搜索	✅	仅限关键词搜索
跨已连接应用的 AI 连接器搜索	✅	不可用
以 Markdown 原生方式读取和编辑页面	✅	仅限于两个页面内容工具
无缝的 OAuth 设置	✅	手动令牌和 JSON 配置
尊重每个用户现有的 Notion 权限	✅	手动集成权限和页面共享
积极支持和持续改进	✅	不积极支持

在 远程 Notion MCP 文档 中了解更多信息并开始使用。

我们优先考虑并仅对 远程 Notion MCP 提供积极支持。因此：

• 我们将来可能会停止维护此本地 MCP 服务器仓库。
• 此处的问题和拉取请求不会得到积极监控。
• 请勿在此处提交与远程 MCP 相关的问题；请改为联系 Notion 支持。

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

---

⚠️ 版本 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 并创建一个新的内部集成或选择一个现有的集成。

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

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

2. 将内容连接到集成

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

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

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

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_**** 替换为你的集成密钥。你可以在集成配置选项卡中找到它：

传输选项

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

然后，客户端在 initialize 请求中使用专用的 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

每个连接解析令牌的方式，按顺序：

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

注意：

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

示例

1. 使用以下指令

Comment "Hello MCP" on page "Getting started"

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

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

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

1. 你也可以直接引用内容 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 中本地测试更改：

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

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

发布

npm login
npm publish --access public