Notion MCP 服务器

[!NOTE]

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

• 通过标准 OAuth 即可轻松安装。无需再手动处理 JSON 或 API 令牌。
• 强大的工具专为 AI 代理设计，包括以 Markdown 编辑页面的功能。这些工具在设计时充分考虑了优化的 token 消耗。

了解更多信息并开始使用，请访问 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 个）

---

安装

1. 在 Notion 中设置集成

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

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

例如，您可以在“配置”选项卡中仅授予“读取内容”权限，从而创建一个只读集成令牌：

2. 将内容连接到集成

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

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

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

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 传输方式。

# 使用默认 stdio 传输运行
npx @notionhq/notion-mcp-server

# 或者显式指定 stdio
npx @notionhq/notion-mcp-server --transport stdio

可流式 HTTP 传输

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

# 使用可流式 HTTP 传输，默认端口 3000
npx @notionhq/notion-mcp-server --transport http

# 使用自定义端口
npx @notionhq/notion-mcp-server --transport http --port 8080

# 使用自定义身份验证令牌运行
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

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

身份验证

为了安全起见，可流式 HTTP 传输需要使用 Bearer 令牌进行身份验证。您有三种选项：

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

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

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

已生成的身份验证令牌：a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab
请在 Authorization 头部使用此令牌：Bearer a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab

选项 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 请求

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

# 示例请求
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 环境变量。

示例

1. 使用以下指令：

   在“入门”页面上评论“Hello MCP”
   

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

2. 类似地，以下指令将在父页面“开发”中添加一个名为“Notion MCP”的新页面：

   在“开发”页面上添加一个标题为“Notion MCP”的页面
   

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

   获取页面 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

Notion MCP Server 快速上手指南

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：macOS, Linux 或 Windows (需安装 Node.js 环境)
• 运行时依赖：
  • Node.js (推荐 v18 或更高版本)
  • npx (随 Node.js 自动安装)
  • 或者使用 Docker (可选方案)
• Notion 账号：拥有管理员权限的工作区
• AI 客户端：支持 MCP 协议的客户端 (如 Cursor, Claude Desktop, Zed, GitHub Copilot CLI 等)

⚠️ 重要提示：本项目 (本地服务器) 未来可能停止维护。Notion 官方推荐使用基于 OAuth 的远程 Notion MCP。若需长期稳定使用，建议参考 Notion 官方文档。本指南仅针对当前开源的本地版本。

安装步骤

第一步：配置 Notion 集成

1. 访问 Notion 集成管理页面。
2. 点击 + New integration 创建一个新的 Internal integration (内部集成)。
3. 在 Configuration 标签页中：
   • 复制 Internal Integration Token (格式为 ntn_...)，稍后配置时需要。
   • (可选) 为了安全，可在 Capabilities 中仅勾选 "Read content" 实现只读访问。
4. 在 Access 标签页中：
   • 点击 Edit，选择你需要让 AI 访问的页面或数据库。
   • 或者，进入目标 Notion 页面，点击右上角 ··· -> Connect to -> 选择你刚创建的集成。

第二步：配置 AI 客户端

根据你的客户端类型，选择以下一种方式配置。请将 <YOUR_NOTION_TOKEN> 替换为第一步中复制的 Token。

方案 A：Cursor / Claude Desktop (推荐)

编辑配置文件：

• Cursor: .cursor/mcp.json (项目根目录) 或全局配置
• Claude Desktop:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

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

方案 B：Zed Editor

编辑 settings.json：

{
  "context_servers": {
    "notionApi": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "NOTION_TOKEN": "<YOUR_NOTION_TOKEN>"
        }
      },
      "settings": {}
    }
  }
}

方案 C：GitHub Copilot CLI

运行交互式命令：

/mcp add

按提示输入，或手动编辑 ~/.copilot/mcp-config.json：

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

方案 D：Docker 运行

如果你偏好容器化部署，可使用官方镜像：

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

基本使用

配置完成后，重启你的 AI 编辑器或客户端。MCP 工具会自动加载，无需额外代码。

核心功能变化 (v2.0+)

版本 2.0 已将“数据库 (Database)"抽象升级为“数据源 (Data Source)"。旧的工具名称（如 post-database-query）已废弃，新工具包括 query-data-source, create-a-data-source 等。AI 会自动识别新工具，但若你在 Prompt 中硬编码了旧工具名，请更新为新名称。

使用示例

直接在对话框中使用自然语言指令即可：

示例 1：搜索并评论

"在 'Getting started' 页面上评论 'Hello MCP'" (AI 将自动调用 search 和 comments 接口)

示例 2：创建页面

"在 'Development' 页面下创建一个标题为 'Notion MCP' 的新页面"

示例 3：查询内容

"获取页面 ID 为 1a6b35e6e67f802fa7e1d27686f017f2 的内容"

示例 4：操作数据源 (原数据库操作)

"查询 'Project Tasks' 数据源中状态为 'Done' 的所有条目"

高级用法：HTTP 模式

若需通过 HTTP 暴露服务（例如供 Web 应用调用），可使用 Streamable HTTP 传输模式：

# 启动 HTTP 服务 (默认端口 3000)
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

# 设置环境变量启动
export NOTION_TOKEN="<YOUR_NOTION_TOKEN>"
export AUTH_TOKEN="your-secret-token"
npx @notionhq/notion-mcp-server --transport http

服务地址：http://0.0.0.0:3000/mcp 请求时需携带 Header: Authorization: Bearer your-secret-token