Notion MCP Server

Notion MCP 服务

说明

为获得最佳体验，请使用**Remote Notion MCP**， 这是我们官方托管的 MCP 服务。**此仓库是一个独立的可自托管 MCP 服务实现，目前已不再积极维护或提供支持。请改用 Remote Notion MCP。**它专为 AI Agent 打造， 能以少得多的 token 更快地给出结果。

Remote Notion MCP 可以语义搜索你的工作区和已连接的应用，以 Markdown 格式读取和 编辑页面，并仅返回最相关的上下文。这意味着等待时间更短、上下文窗口占用更少、 token 成本更低。它还使用 OAuth，并自动遵循每位用户现有的 Notion 权限——无需 API token、JSON 配置、手动共享页面，也无需维护本地服务。

功能	Remote Notion MCP	此项目（本地）
快速的托管体验	✅	在本地运行和更新
高 token 使用效率的响应	✅	有限
为 AI Agent 量身打造的强大工具	✅	基础的 API 衍生工具
跨 Notion 工作区进行语义搜索	✅	仅支持关键词搜索
跨已连接应用进行 AI Connector 搜索	✅	不支持
原生支持 Markdown 的页面读取和编辑	✅	仅限两种页面内容工具
无缝的 OAuth 设置	✅	手动配置 token 和 JSON
遵循每位用户现有的 Notion 权限	✅	手动配置集成权限并共享页面
积极的支持和持续改进	✅	不再积极提供支持

请在 Remote Notion MCP 文档中了解详情并开始使用。

我们将优先支持且仅积极支持 Remote Notion MCP。因此：

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

此项目实现了一个用于 Notion API 的 MCP 服务。

---

⚠️ Version 2.0.0 重大变更

Version 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 Agent 的令牌使用效率：

• 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 删除数据库），但将其开放给大模型仍会给工作区数据带来一定风险。注重安全的用户可能希望进一步配置集成的 Capabilities。

例如，你可以在“Configuration”选项卡中仅授予“Read content”权限，从而创建只读集成令牌：

2. 将内容连接到集成

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

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

或者，你也可以单独授予页面访问权限。前往目标页面，点击右上角的三个点，然后选择“Connect to integration”。

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 Server 支持两种传输模式：

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

Streamable HTTP 传输

对于基于 Web 的应用或偏好使用 HTTP 通信的客户端，可以使用 Streamable 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"

使用 Streamable HTTP 传输时，服务默认可通过 http://127.0.0.1:<port>/mcp 访问。

身份验证

Streamable HTTP 传输需要使用 bearer token 身份验证来确保安全。你有三种选择：

选项 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 环境变量，命令行参数 --auth-token 的优先级更高。

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

只有使用明确的不安全标志，才能禁用 bearer token 身份验证：

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

警告：--unsafe-disable-auth 不安全。你访问的网页可能通过 DNS 重绑定访问该服务。仅在隔离网络中使用。

禁用身份验证后，服务会将 Host 和 Origin 标头与配置的本地主机和环回主机进行比对，以启用 DNS 重绑定保护。之前的 --disable-auth 标志仍可用作已弃用的别名，但会打印警告。

发起 HTTP 请求

所有发往 Streamable HTTP 传输的请求都必须在 Authorization 标头中包含 bearer token：

# 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 环境变量（推荐），或设置包含 Notion 集成令牌的 OPENAPI_MCP_HEADERS 环境变量。

为多个集成提供服务（按请求传递令牌）

默认情况下，服务会在启动时使用内置的单个令牌向 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