Stack Notion MCP Supergateway

概念MCP服务器Docker堆栈

此存储库提供 双重运输 Docker部署 MCP服务器概念 这两者都适用 克劳德桌面版 （STDIO）和 n8n （HTTP/SSE）无缝连接。

概述

Notion MCP服务器允许AI助手与您的Notion工作区进行交互。这个增强的Docker堆栈会自动在传输模式之间切换：

• 🖥️ STDIO模式：与Claude Desktop直接集成
• 🌐 HTTP/SSE模式：n8n和其他HTTP客户端的基于Web的访问
• 🔄 自动模式检测：相同的容器映像适用于这两种用例
• 🔐 双重身份验证：用于传输安全和Notion API访问的独立令牌

先决条件

• Docker和Docker Compose
• Notion集成令牌(在此处创建一个)
• （可选）n8n实例用于AI代理集成

快速开始

1.环境设置

创建一个 .env 使用您的令牌文件：

# Notion API authentication (get from https://www.notion.so/my-integrations)
NOTION_TOKEN=ntn_your_actual_token_here

# Transport authentication (generate with: openssl rand -hex 32)
MCP_AUTH_TOKEN=0b55ef9cf8e82a26447d7b2b8ce8fe18179c88d2a5a2ac50d45cffb8ee714d14

环境变量引用

这 .env 文件包含以下配置变量：

重要提示：

• NOTION_VERSION 仅在您取消注释时使用 OPENAPI_MCP_HEADERS docker-compose.yml中的覆盖

- 自动构造（默认）：使用硬编码 2025-09-03 从Dockerfile - 带有覆盖（未注释）：用途 ${NOTION_VERSION} 来自.env

• IMAGE_REGISTRY_URL 是 仅注册表路径，不是完整的图像名称

- ✅ 对的： registry.gitlab.com/my_group - ❌ 错误： registry.gitlab.com/my_group/stack-notion-mcp-supergateway:v0.3.0

• 完整图像参考构造如下： ${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:v0.3.0
• 如果你分叉这个项目，更新 IMAGE_REGISTRY_URL 指向您自己的注册表

2.部署容器

docker-compose up -d

就是这样！ 您的Notion MCP服务器现在可以通过HTTP/SSE进行n8n集成访问。

主要用例：n8n集成

🎯 主要用途： 该项目的主要目标是使 n8n访问Notion MCP 通过HTTP/SSE端点，自官方 @notionhq/notion-mcp-server 仅支持STDIO模式。

⚡ 对于n8n用户： 这是 唯一途径 在n8n工作流中使用Notion MCP-超级网关包装器将STDIO转换为HTTP/SSE传输。

用法

对于n8n（HTTP/SSE模式）-主要用例

第一步： 部署容器：

docker-compose up -d

第二步： 配置n8n MCP凭据：

• 统一资源定位符: http://notion-mcp-supergateway:8001/sse
• 认证：承载令牌
• 代币：您的 MCP_AUTH_TOKEN value（不是Notion令牌！）
• 标头：留空

要点：

• ✅ 自动使用HTTP/SSE模式（默认情况下 MCP_TRANSPORT 未设置）
• ✅ n8n只需要 MCP_AUTH_TOKEN 运输安全
• ✅ 容器内部处理Notion API身份验证
• ✅ 清洁分离：传输身份验证与API身份验证

适用于克劳德桌面（STDIO模式）-替代使用

💡 注： 仅适用于Claude Desktop，您可以使用更简单的官方方法： ``json "notion-mcp-server-local": { "command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": { "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_***\", \"Notion-Version\": \"2022-06-28\" }" } } ``

但是，如果你想对n8n和Claude Desktop使用相同的Docker镜像：

将此配置添加到您的Claude Desktop配置文件中(~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "notion-mcp-supergateway": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "NOTION_TOKEN=ntn_your_actual_token_here",
        "-e", "SKIP_SSL_ERRORS=1",
        "${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:v0.2.1"
      ]
    }
  }
}

在Claude Desktop上使用Docker镜像的权衡：

• ✅ 利益：如果同时使用n8n和Claude Desktop，则采用统一方法
• ✅ 利益：相同的令牌管理和SSL处理
• ❌ 开销：每个Claude会话的Docker容器启动时间
• ❌ 复杂性：更多的资源使用与直接 npx 接近

在以下情况下选择此方法：

• 您已经将其用于n8n，并希望保持一致性
• 您需要增强的SSL/证书处理
• 您更喜欢容器化/隔离执行

选择官方 npx 如果满足以下条件，则采用方法：

• 您仅使用Claude Desktop（非n8n）
• 您希望开销最小，启动速度更快
• 您不需要高级SSL处理

对于n8n（HTTP/SSE模式）

第一步： 部署容器（如果尚未运行）：

docker-compose up -d

第二步： 配置n8n MCP凭据：

• 统一资源定位符: http://notion-mcp-supergateway:8001/sse
• 认证：承载令牌
• 代币：您的 MCP_AUTH_TOKEN value（不是Notion令牌！）
• 标头：留空

要点：

• ✅ 自动使用HTTP/SSE模式（默认情况下 MCP_TRANSPORT 未设置）
• ✅ n8n只需要 MCP_AUTH_TOKEN 运输安全
• ✅ 容器内部处理Notion API身份验证
• ✅ 清洁分离：传输身份验证与API身份验证

运作原理

令牌流和身份验证

此堆栈使用 两个单独的令牌 用于不同目的：

自动模式检测

相同的Docker镜像会自动检测传输模式：

# Claude Desktop: Detects STDIO mode
if [ "$MCP_TRANSPORT" = "stdio" ]; then
  exec notion-mcp-server;                    # Direct STDIO
else
  exec supergateway --stdio 'notion-mcp-server' --port 8001 --auth ${AUTH_TOKEN};  # HTTP/SSE via Supergateway
fi

内部身份验证处理

容器自动构造正确的Notion API头：

# Your .env: NOTION_TOKEN=ntn_ABC123...
# Container automatically creates: OPENAPI_MCP_HEADERS={"Authorization": "Bearer ntn_ABC123...", "Notion-Version": "2022-06-28"}

这意味着您永远不需要手动格式化Bearer令牌或JSON标头！

配置简化

与以前的版本相比有什么变化

❌ 旧方法（手动收割台施工）：

environment:
  - NOTION_TOKEN=${NOTION_TOKEN}
  - AUTH_TOKEN=${MCP_AUTH_TOKEN}  
  - OPENAPI_MCP_HEADERS={"Authorization":"Bearer ${NOTION_TOKEN}","Notion-Version":"2022-06-28"}  # ← Manual, error-prone

✅ 新方法（自动收割台构造）：

environment:
  - NOTION_TOKEN=${NOTION_TOKEN}           # ← Only need this now!
  - AUTH_TOKEN=${MCP_AUTH_TOKEN}
  # OPENAPI_MCP_HEADERS automatically constructed by container

为何这很重要

1. 消除JSON格式错误 -环境变量中不再有格式错误的JSON
2. 降低.env的复杂性 -简单令牌格式： NOTION_TOKEN=ntn_ABC123...
3. 防止Bearer代币错误 -集装箱搬运 Bearer 自动前缀
4. 版本一致性 -始终使用正确的 Notion-Version: 2025-09-03
5. 与社区解决方案合作 -与现有的MCP模式兼容

Docker镜像现在可以处理以前需要手动配置的内容，使部署更加可靠。

覆盖自动配置

默认情况下，容器会自动构造 OPENAPI_MCP_HEADERS 从你的 NOTION_TOKEN。但是，如果需要，您可以覆盖此行为。

何时覆盖：

• 测试不同的Notion API版本
• 调试特定于API的问题
• 使用自定义标头配置

如何覆盖：

取消注释并修改您的行 docker-compose.yml:

environment:
  - NOTION_TOKEN=${NOTION_TOKEN}
  - AUTH_TOKEN=${MCP_AUTH_TOKEN}
  - OPENAPI_MCP_HEADERS={"Authorization":"Bearer ${NOTION_TOKEN}","Notion-Version":"2025-09-03"}  # Uncomment to override automatic construction

⚠️ 警告： 手动超控禁用自动构造。确保JSON格式正确，否则容器将无法启动。

网络配置

Docker网络

该服务连接到两个网络以获得最佳性能：

• mcp-network：MCP服务通信的内部网络
• n8n-network：用于n8n集成的外部网络（自动创建）

Docker网络集成的好处

对于n8n用户：

• 直接集装箱通信：用途 http://notion-mcp-supergateway:8001/sse 而不是外部URL
• 减少延迟：绕过代理隧道和外部路由
• 更高的可靠性：不依赖于外部网络可用性
• 更好的安全性：通信保持在Docker网络内

n8n集成（可选）

高级配置

SSL证书处理

对于公司环境或自定义SSL设置：

# Option 1: Skip SSL validation (development only)
SKIP_SSL_ERRORS=1

# Option 2: Use custom CA certificate
CORPORATE_CA_CERT="-----BEGIN CERTIFICATE-----
MIIFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END CERTIFICATE-----"

测试HTTP/SSE设置

要验证您的MCP服务器是否正常工作：

第一步： 启动SSE连接

curl -H "Authorization: Bearer ${MCP_AUTH_TOKEN}" -N "http://localhost:8001/sse"
# Note the sessionId from the response

第二步： 使用步骤1中的会话ID进行测试

curl -H "Authorization: Bearer ${MCP_AUTH_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}}, "id": 1}' \
     "http://localhost:8001/message?sessionId=YOUR-SESSION-ID-HERE"

预期响应： Accepted 表示MCP服务器工作正常。

构建和部署

构建新版本

当您需要更新Docker镜像时（例如，更新Notion API版本或添加功能）：

步骤1：构建图像

docker-compose -f docker-compose-build.yml build

步骤2：标记新版本

# Tag with specific version (e.g., v0.3.0)
docker tag stack-notion-mcp-supergateway:latest ${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:v0.3.0

# Also update the 'latest' tag
docker tag stack-notion-mcp-supergateway:latest ${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:latest

步骤3：推送到GitLab注册表

docker push ${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:v0.3.0
docker push ${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:latest

步骤4：更新克劳德桌面（如果适用）

编辑 ~/.claude/claude_desktop_config.json 要使用新版本，请执行以下操作：

{
  "mcpServers": {
    "notion-mcp-supergateway-local": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "NOTION_TOKEN=ntn_your_token_here",
        "-e", "SKIP_SSL_ERRORS=1",
        "${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:v0.3.0"
      ]
    }
  }
}

然后重新启动Claude Desktop以使用新版本。

步骤5：更新正在运行的容器（适用于n8n/HTTP模式）

# Stop and remove old container
docker stop notion-mcp-supergateway
docker rm notion-mcp-supergateway

# Update docker-compose.yml to use new version
# Then start with new version
docker-compose up -d

版本编号

遵循语义版本控制：

• 专业（v1.0.0→ v2.0.0）：中断更改（例如，API更改、删除的功能）
• 轻微（v0.2.0→ v0.3.0）：新功能，非中断性更改（例如，API版本更新）
• 补丁（v0.2.1→ v0.2.2）：Bug修复，细微改进

故障排除

常见问题

“Notion MCP服务器返回身份验证错误”

• ❌ 问题：缺失或无效 NOTION_TOKEN
• ✅ 解决方案：验证令牌以开头 ntn_ 并具有适当的Notion集成权限

n8n连接被拒绝

• ❌ 问题：URL错误或缺少承载令牌
• ✅ 解决方案：使用 http://notion-mcp-supergateway:8001/sse 和你的 MCP_AUTH_TOKEN

克劳德桌面未连接

• ❌ 问题：缺失 MCP_TRANSPORT=stdio 环境变量
• ✅ 解决方案：将环境变量添加到Claude配置中

调试日志记录

要查看详细的容器日志：

docker logs notion-mcp-supergateway -f

寻找这些启动指标：

• ✅ Constructed OPENAPI_MCP_HEADERS from NOTION_TOKEN
• 🔗 Starting in STDIO mode for Claude Desktop （克劳德）
• 🌐 Starting in HTTP/SSE mode via Supergateway （n8n）

版本历史记录

v0.3.0-通知API更新（2025）

• ✅ 更新了来自的Notion API版本 2022-06-28 到 2025-09-03
• ✅ 添加了构建和部署文档
• ✅ 修复了docker组成镜像命名（删除重复）
• ✅ 改进了版本管理和标记过程

v0.2.1-增强的双传输支持

• ✅ 已添加自动 OPENAPI_MCP_HEADERS 建设从 NOTION_TOKEN
• ✅ 实现了双传输模式（克劳德桌面的STDIO，n8n的HTTP/SSE）
• ✅ 通过以下方式增强SSL证书处理 SKIP_SSL_ERRORS 支持
• ✅ 简化的Docker Compose配置
• ✅ 添加了全面的启动日志记录和错误处理

v0.1.0-初始版本

• 带超级网关包装器的MCP服务器基本概念

贡献

基于社区解决方案，并增强了生产就绪功能。欢迎投稿！

主要贡献者

原始设备制造商