AI导哈

Notion MCP服务器

Notion MCP是一个远程MCP服务器，通过标准OAuth简化安装过程，提供专为AI代理设计的工具，优化令牌消耗。

  • by waimakers
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Generative-AI-Strategy-B-V/notion-mcp

使用说明

MCP服务器概念

[！注意]

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

  • 通过标准OAuth轻松安装。不再需要摆弄JSON或API令牌。
  • 为AI代理量身定制的强大工具。这些工具的设计考虑到了优化的代币消费。

了解更多并尝试一下 这里

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

安装

1.在理念上建立一体化：

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

虽然我们限制了Notion API暴露的范围（例如，您将无法通过MCP删除数据库），但将工作空间数据暴露给LLM会带来非零风险。有安全意识的用户可能希望进一步配置集成 能力.

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

2.将内容连接到集成：

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

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

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

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

使用npm：

光标和克劳德：

将以下内容添加到您的 .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\": \"2022-06-28\" }"
      }
    }
  }
}

泽德

将以下内容添加到您的 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\": \"2022-06-28\" }"
        }
      },
      "settings": {}
    }
  }
}
使用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\":\"2022-06-28\"}"
      }
    }
  }
}

这种方法：

  • 使用官方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\": \"2022-06-28\"}",
        "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通信的客户端，您可以使用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

# 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：自动生成令牌（建议用于开发）

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

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

Generated auth token: a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789ab
Use this token in the Authorization header: 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请求

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

# 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. 使用以下说明
Comment "Hello MCP" on page "Getting started"

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

  1. 同样，以下指令将导致一个名为“Notion MCP”的新页面添加到父页面“Development”中
Add a page titled "Notion MCP" to page "Development"
  1. 您也可以直接引用内容ID
Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

发展

构建

npm run build

执行

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

发布

npm publish --access public

相关 MCP