Notion MCP Server

This project implements an MCP server for the Notion API.

MCP Compliance

This server is fully compliant with the Model Context Protocol (MCP) specification:

• MCP SDK: Built on @modelcontextprotocol/sdk version 1.8.0
• Transport Support:
  • Stdio transport for local execution
  • SSE (Server-Sent Events) transport for remote connections
• Protocol Features:
  • Tool listing and discovery
  • Tool execution with structured input/output
  • Error handling and status reporting
  • Multiple concurrent connections (remote mode)
• Configuration:
  • Environment variables (stdio mode)
  • Query parameters (remote mode)
  • Per-connection configuration support

For remote deployment information, see REMOTE_DEPLOYMENT.md.

For Google Cloud Run specific deployment, see CLOUD_RUN_DEPLOY.md.

Installation

1. Setting up Integration in Notion:

Go to https://www.notion.so/profile/integrations and create a new internal integration or select an existing one.

While we limit the scope of Notion API's exposed (for example, you will not be able to delete databases via MCP), there is a non-zero risk to workspace data by exposing it to LLMs. Security-conscious users may want to further configure the Integration's Capabilities.

For example, you can create a read-only integration token by giving only "Read content" access from the "Configuration" tab:

2. Connecting content to integration:

Ensure relevant pages and databases are connected to your integration.

To do this, you'll need to visit that page, and click on the 3 dots, and select "Connect to integration".

3. Adding MCP config to your client:

Using npm:

Add the following to your .cursor/mcp.json or claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "ntn_****",
        "NOTION_API_VERSION": "2022-06-28"  // Optional, defaults to 2022-06-28
      }
    }
  }
}

Using Docker:

There are three options for running the MCP server with Docker:

Option 1: Using the official Docker Hub image (stdio mode):

Add the following to your .cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_API_KEY",
        "-e", "NOTION_API_VERSION",
        "mcp/notion"
      ],
      "env": {
        "NOTION_API_KEY": "ntn_****",
        "NOTION_API_VERSION": "2022-06-28"  // Optional, defaults to 2022-06-28
      }
    }
  }
}

This approach:

• Uses the official Docker Hub image
• Uses simple environment variables for configuration
• Provides a more reliable configuration method

Option 2: Building the Docker image locally (stdio mode):

You can also build and run the Docker image locally. First, build the Docker image:

# Standard build (compatible with all Docker versions)
docker build -t notion-mcp-server .

# Or use Docker Compose
docker-compose build

# Optional: BuildKit-optimized build (faster, requires Docker 18.09+)
DOCKER_BUILDKIT=1 docker build -f Dockerfile.buildkit -t notion-mcp-server .

Then, add the following to your .cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_API_KEY=ntn_****",
        "-e", "NOTION_API_VERSION=2022-06-28",  # Optional, defaults to 2022-06-28
        "notion-mcp-server"
      ]
    }
  }
}

Option 3: Remote MCP Server (HTTP/SSE mode):

For remote connections, you can run the server in HTTP mode with SSE transport. This allows multiple clients to connect and pass configuration via query parameters.

First, start the remote server:

docker-compose up notion-mcp-server

Or run directly with Docker:

docker run -p 3000:3000 notion-mcp-server

The server will start on port 3000 (configurable via PORT environment variable).

Then, configure your MCP client to connect remotely:

{
  "mcpServers": {
    "notionApi": {
      "url": "http://localhost:3000/sse",
      "queryParams": {
        "notionApiKey": "ntn_****",
        "baseUrl": "https://api.notion.com",
        "notionApiVersion": "2022-06-28"
      }
    }
  }
}

Query Parameters:

• notionApiKey (required): Your Notion integration API key
• baseUrl (optional): Notion API base URL (default: https://api.notion.com)
• notionApiVersion (optional): Notion API version (default: 2022-06-28)

Benefits of Remote Mode:

• Multiple clients can connect simultaneously
• Configuration per connection (each client can use different API keys)
• No need to restart server for different configurations
• Suitable for cloud deployments
• Health check endpoint at /health

Security Note: When running in remote mode, ensure proper network security measures are in place, especially if exposing the server to the internet. Consider using HTTPS, authentication middleware, and firewall rules.

Don't forget to replace ntn_**** with your integration secret. Find it from your integration configuration tab:

Installing via Smithery

To install Notion API Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @makernotion/notion-mcp-server --client claude

Configuration Examples

For more configuration examples including remote mode, Docker, and multiple workspace setups, see mcp-config-examples.json.

Examples

1. Using the following instruction

Comment "Hello MCP" on page "Getting started"

AI will correctly plan two API calls, v1/search and v1/comments, to achieve the task

2. Similarly, the following instruction will result in a new page named "Notion MCP" added to parent page "Development"

Add a page titled "Notion MCP" to page "Development"

3. You may also reference content ID directly

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

Development

Build

npm run build

Execute (stdio mode)

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

Run Remote Server (development)

npm run dev:remote

This will start the remote MCP server on port 3000 with hot-reload enabled. Connect to it at:

http://localhost:3000/sse?notionApiKey=YOUR_KEY&baseUrl=https://api.notion.com&notionApiVersion=2022-06-28

Testing Remote Server

Once the remote server is running, you can test it:

# Health check
curl http://localhost:3000/health

# Test SSE connection (requires MCP client or tool)
curl "http://localhost:3000/sse?notionApiKey=YOUR_KEY&notionApiVersion=2022-06-28"

Publish

npm publish --access public