stack-notion-mcp-supergateway

oemden/stack-notion-mcp-supergateway

3.1

If you are the rightful owner of stack-notion-mcp-supergateway and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Notion MCP Server Docker Stack provides a dual-transport deployment solution for integrating AI assistants with Notion workspaces, supporting both Claude Desktop and n8n platforms.

Notion MCP Server Docker Stack

This repository provides a dual-transport Docker deployment of the Notion MCP Server that works with both Claude Desktop (STDIO) and n8n (HTTP/SSE) seamlessly.

Overview

The Notion MCP Server allows AI assistants to interact with your Notion workspace. This enhanced Docker stack automatically switches between transport modes:

  • 🖥️ STDIO Mode: Direct integration with Claude Desktop
  • 🌐 HTTP/SSE Mode: Web-based access for n8n and other HTTP clients
  • 🔄 Automatic Mode Detection: Same container image works for both use cases
  • 🔐 Dual Authentication: Separate tokens for transport security and Notion API access

Prerequisites

  • Docker and Docker Compose
  • A Notion integration token (Create one here)
  • (Optional) n8n instance for AI agent integration

Quick Start

1. Environment Setup

Create a .env file with your tokens:

# 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

Environment Variables Reference

The .env file contains the following configuration variables:

VariableDescriptionExampleRequired
NOTION_TOKENNotion API integration token. Get from notion.so/my-integrationsntn_ABC123...✅ Yes
MCP_AUTH_TOKENTransport security token for HTTP/SSE access. Generate with openssl rand -hex 320b55ef9cf8e...✅ Yes (for n8n mode)
NOTION_VERSIONNotion API version to use. Only applies when OPENAPI_MCP_HEADERS override is uncommented2025-09-03⚠️ Optional (for override)
IMAGE_REGISTRY_URLDocker registry path (without image name or tag). Used for custom/private registriesregistry.gitlab.com/my_group⚠️ Optional (for deployment)

Important Notes:

  • NOTION_VERSION is only used when you uncomment the OPENAPI_MCP_HEADERS override in docker-compose.yml
    • With automatic construction (default): Uses hardcoded 2025-09-03 from Dockerfile
    • With override (uncommented): Uses ${NOTION_VERSION} from .env
  • IMAGE_REGISTRY_URL is just the registry path, not the full image name
    • ✅ Correct: registry.gitlab.com/my_group
    • ❌ Wrong: registry.gitlab.com/my_group/stack-notion-mcp-supergateway:v0.3.0
  • The full image reference is constructed as: ${IMAGE_REGISTRY_URL}/stack-notion-mcp-supergateway:v0.3.0
  • If you fork this project, update IMAGE_REGISTRY_URL to point to your own registry

2. Deploy the Container

docker-compose up -d

That's it! Your Notion MCP server is now accessible via HTTP/SSE for n8n integration.

Primary Use Case: n8n Integration

🎯 Main Purpose: The primary goal of this project is to enable n8n access to Notion MCP via HTTP/SSE endpoints, since the official @notionhq/notion-mcp-server only supports STDIO mode.

⚡ For n8n users: This is the only way to use Notion MCP in n8n workflows - the Supergateway wrapper converts STDIO to HTTP/SSE transport.

Usage

For n8n (HTTP/SSE Mode) - Primary Use Case

Step 1: Deploy the container:

docker-compose up -d

Step 2: Configure n8n MCP credential:

  • URL: http://notion-mcp-supergateway:8001/sse
  • Authentication: Bearer Token
  • Token: Your MCP_AUTH_TOKEN value (not the Notion token!)
  • Headers: Leave empty

Key Points:

  • ✅ Uses HTTP/SSE mode automatically (default when MCP_TRANSPORT not set)
  • ✅ n8n only needs the MCP_AUTH_TOKEN for transport security
  • ✅ Container handles Notion API authentication internally
  • ✅ Clean separation: transport auth vs API auth

For Claude Desktop (STDIO Mode) - Alternative Use

💡 Note: For Claude Desktop only, you could use the simpler official approach:

"notion-mcp-server-local": {
  "command": "npx",
  "args": ["-y", "@notionhq/notion-mcp-server"],
  "env": {
    "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_***\", \"Notion-Version\": \"2022-06-28\" }"
  }
}

However, if you want to use the same Docker image for both n8n and Claude Desktop:

Add this configuration to your Claude Desktop config file (~/.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"
      ]
    }
  }
}

Trade-offs of using Docker image for Claude Desktop:

  • ✅ Benefit: Unified approach if you use both n8n and Claude Desktop
  • ✅ Benefit: Same token management and SSL handling
  • ❌ Overhead: Docker container startup time per Claude session
  • ❌ Complexity: More resource usage vs direct npx approach

Choose this approach if:

  • You're already using this for n8n and want consistency
  • You need the enhanced SSL/certificate handling
  • You prefer containerized/isolated execution

Choose the official npx approach if:

  • You only use Claude Desktop (not n8n)
  • You want minimal overhead and faster startup
  • You don't need advanced SSL handling

For n8n (HTTP/SSE Mode)

Step 1: Deploy the container (if not already running):

docker-compose up -d

Step 2: Configure n8n MCP credential:

  • URL: http://notion-mcp-supergateway:8001/sse
  • Authentication: Bearer Token
  • Token: Your MCP_AUTH_TOKEN value (not the Notion token!)
  • Headers: Leave empty

Key Points:

  • ✅ Uses HTTP/SSE mode automatically (default when MCP_TRANSPORT not set)
  • ✅ n8n only needs the MCP_AUTH_TOKEN for transport security
  • ✅ Container handles Notion API authentication internally
  • ✅ Clean separation: transport auth vs API auth

How It Works

Token Flow & Authentication

This stack uses two separate tokens for different purposes:

TokenPurposeUsed ByFormat
NOTION_TOKENNotion API authenticationContainer → Notion APIntn_ABC123...
MCP_AUTH_TOKENTransport securityn8n → ContainerAny secure string

Automatic Mode Detection

The same Docker image automatically detects the transport mode:

# 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

Internal Authentication Handling

The container automatically constructs the proper Notion API headers:

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

This means you never need to manually format Bearer tokens or JSON headers!

Configuration Simplification

What Changed from Previous Versions

❌ Old approach (manual header construction):

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

✅ New approach (automatic header construction):

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

Why This Matters

  1. Eliminates JSON formatting errors - No more malformed JSON in environment variables
  2. Reduces .env complexity - Simple token format: NOTION_TOKEN=ntn_ABC123...
  3. Prevents Bearer token mistakes - Container handles the Bearer prefix automatically
  4. Version consistency - Always uses the correct Notion-Version: 2025-09-03
  5. Works with community solutions - Compatible with existing MCP patterns

The Docker image now handles what previously required manual configuration, making deployment much more reliable.

Overriding Automatic Configuration

By default, the container automatically constructs OPENAPI_MCP_HEADERS from your NOTION_TOKEN. However, you can override this behavior if needed.

When to override:

  • Testing different Notion API versions
  • Debugging API-specific issues
  • Using custom header configurations

How to override:

Uncomment and modify the line in your 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

⚠️ Warning: Manual override disables automatic construction. Ensure JSON is properly formatted or the container will fail to start.

Network Configuration

Docker Networks

The service connects to two networks for optimal performance:

  • mcp-network: Internal network for MCP services communication
  • n8n-network: External network for n8n integration (automatically created)

Benefits of Docker Network Integration

For n8n users:

  • Direct container communication: Uses http://notion-mcp-supergateway:8001/sse instead of external URLs
  • Lower latency: Bypasses proxy tunnels and external routing
  • Higher reliability: No dependency on external network availability
  • Better security: Communication stays within Docker network

n8n Integration (Optional)

Advanced Configuration

SSL Certificate Handling

For corporate environments or custom SSL setups:

# 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-----"

Testing the HTTP/SSE Setup

To verify your MCP server is working correctly:

Step 1: Start SSE connection

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

Step 2: Test with the sessionId from step 1

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"

Expected Response: Accepted indicates the MCP server is working correctly.

Building and Deployment

Building a New Version

When you need to update the Docker image (e.g., updating Notion API version or adding features):

Step 1: Build the image

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

Step 2: Tag the new version

# 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

Step 3: Push to GitLab registry

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

Step 4: Update Claude Desktop (if applicable)

Edit ~/.claude/claude_desktop_config.json to use the new version:

{
  "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"
      ]
    }
  }
}

Then restart Claude Desktop to use the new version.

Step 5: Update running containers (for n8n/HTTP mode)

# 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

Version Numbering

Follow semantic versioning:

  • Major (v1.0.0 → v2.0.0): Breaking changes (e.g., API changes, removed features)
  • Minor (v0.2.0 → v0.3.0): New features, non-breaking changes (e.g., API version updates)
  • Patch (v0.2.1 → v0.2.2): Bug fixes, minor improvements

Troubleshooting

Common Issues

"Notion MCP server returned an authentication error"

  • ❌ Problem: Missing or invalid NOTION_TOKEN
  • ✅ Solution: Verify token starts with ntn_ and has proper Notion integration permissions

n8n connection refused

  • ❌ Problem: Wrong URL or missing Bearer token
  • ✅ Solution: Use http://notion-mcp-supergateway:8001/sse and your MCP_AUTH_TOKEN

Claude Desktop not connecting

  • ❌ Problem: Missing MCP_TRANSPORT=stdio environment variable
  • ✅ Solution: Add the environment variable to your Claude config

Debug Logging

To see detailed container logs:

docker logs notion-mcp-supergateway -f

Look for these startup indicators:

  • ✅ Constructed OPENAPI_MCP_HEADERS from NOTION_TOKEN
  • 🔗 Starting in STDIO mode for Claude Desktop (Claude)
  • 🌐 Starting in HTTP/SSE mode via Supergateway (n8n)

Version History

v0.3.0 - Notion API Update (2025)

  • ✅ Updated Notion API version from 2022-06-28 to 2025-09-03
  • ✅ Added building and deployment documentation
  • ✅ Fixed docker-compose image naming (removed duplication)
  • ✅ Improved version management and tagging process

v0.2.1 - Enhanced Dual Transport Support

  • ✅ Added automatic OPENAPI_MCP_HEADERS construction from NOTION_TOKEN
  • ✅ Implemented dual transport mode (STDIO for Claude Desktop, HTTP/SSE for n8n)
  • ✅ Enhanced SSL certificate handling with SKIP_SSL_ERRORS support
  • ✅ Simplified Docker Compose configuration
  • ✅ Added comprehensive startup logging and error handling

v0.1.0 - Initial Release

  • Basic Notion MCP Server with Supergateway wrapper

Contributing

Based on community solutions and enhanced with production-ready features. Contributions welcome!

Main Contributor

oem oem@mobiloem.local