⚙

Notion MCP服务器

Notion MCP是一个远程MCP服务器，提供简化的OAuth安装和专为AI代理设计的强大工具，如Markdown页面编辑。

作者 By makenotion
本地部署 MCP服务器 Notion集成
GitHub

MCP服务器概念

[！注意]

我们介绍 MCP概念，具有以下改进的远程MCP服务器：

  • 通过标准OAuth轻松安装。不再需要摆弄JSON或API令牌。

  • 为AI代理量身定制的强大工具，包括用Markdown编辑页面。这些工具的设计考虑到了优化的代币消费。

了解更多信息并开始使用 MCP文件概念.

我们正在优先考虑，并且只提供积极支持， MCP概念 （远程）。因此：

  • 我们将来可能会关闭这个本地MCP服务器存储库。
  • 这里的问题和拉取请求没有受到主动监控。
  • 请不要在此处提交与远程MCP有关的问题；相反，请联系Notion支持。

该项目实现了 MCP服务器 为了 API通知.

⚠️ 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-queryquery-data-sourcedatabase_id → data_source_id
update-a-databaseupdate-a-data-sourcedatabase_id → data_source_id
create-a-databasecreate-a-data-source无变化（使用 parent.page_id)

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

当前工具总数：22 （v1.x中为19）

安装

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（推荐）

JSON``` 1 2 3 4 5 6 7 8 9 10 11{ “mcpServers”: { “notionApi”: { “command”: “npx”, “args”: [“-y”, “@notionhq/notion-mcp-server”], “env”: { “NOTION_TOKEN”: “ntn_****” } } } }


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


JSON```
1
2
3
4
5
6
7
8
9
10
11{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}
泽德

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

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14{ “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命令行界面


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


BASH```
1/mcp add

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

JSON``` 1 2 3 4 5 6 7 8 9 10 11{ “mcpServers”: { “notionApi”: { “command”: “npx”, “args”: [“-y”, “@notionhq/notion-mcp-server”], “env”: { “NOTION_TOKEN”: “ntn_****” } } } }


有关更多信息，请参阅 [Copilot CLI文档](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).


##### 使用Docker


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


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


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


使用NOTION_TOKEN（推荐）：


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

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

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17{ “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镜像：


BASH```
1docker compose build

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

使用NOTION_TOKEN（推荐）：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15{ “mcpServers”: { “notionApi”: { “command”: “docker”, “args”: [ “run”, “—rm”, “-i”, “-e”, “NOTION_TOKEN=ntn_****”, “notion-mcp-server” ] } } }


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


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
  "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传输。

BASH``` 1 2 3 4# Run with default stdio transport npx @notionhq/notion-mcp-server

Or explicitly specify stdio

npx @notionhq/notion-mcp-server —transport stdio


#### 可流式HTTP传输


对于基于web的应用程序或更喜欢HTTP通信的客户端，您可以使用Streamable HTTP传输：


BASH```
1
2
3
4
5
6# 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
# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

使用Streamable HTTP传输时，服务器将在 http://0.0.0.0:<port>/mcp.

认证

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

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

BASH``` 1npx @notionhq/notion-mcp-server —transport http


服务器将生成一个安全的随机令牌并将其显示在控制台中：


TEXT```
1
2Generated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab
Use this token in the Authorization header: Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab
选项2：通过命令行自定义令牌（建议用于生产）

BASH``` 1npx @notionhq/notion-mcp-server —transport http —auth-token “your-secret-token”


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


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

命令行参数 --auth-token 优先于 AUTH_TOKEN 如果两者都提供，则为环境变量。

发出HTTP请求

对Streamable HTTP传输的所有请求都必须在Authorization标头中包含承载令牌：

BASH``` 1 2 3 4 5 6# 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集成令牌的环境变量。


### 例子


1. 使用以下说明


TEXT```
1Comment "Hello MCP" on page "Getting started"

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

  1. 同样，以下指令将导致一个名为“Notion MCP”的新页面添加到父页面“Development”中

TEXT``` 1Add a page titled “Notion MCP” to page “Development”


1. 您也可以直接引用内容ID


TEXT```
1Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

发展

构建和测试

BASH``` 1 2npm run build npm test


#### 执行


BASH```
1npx -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 从存储库根目录。

JSON``` 1 2 3 4 5 6 7 8 9 10{ “mcpServers”: { “notion-local-package”: { “command”: “notion-mcp-server”, “env”: { “NOTION_TOKEN”: “ntn_…” } } } }


#### 发布


BASH```
1
2npm login
npm publish --access public