Notion MCP Server

Notion MCP (Model Context Protocol) server for Claude Code integration.

Overview

This server connects your Notion workspace to Claude Code, enabling Claude to search, read, and write Notion pages directly.

Features

• 🔍 Search Notion pages and databases
• 📖 Read page content and database entries
• ✍️ Create and update pages
• 🔎 Query databases with filters and sorting
• 🔐 Secure API key management
• 🚀 Full Notion API integration

Quick Start

For most users, use stdio mode (simpler and more stable):

# 1. Install
npm install && npm run build

# 2. Get Notion API key from https://www.notion.so/my-integrations

# 3. Register with Claude Code
claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=your_key_here \
  -- node /absolute/path/to/dist/index.js

# 4. Use in Claude Code
claude
> /mcp
> 내 Notion 페이지를 검색해줘

📘 Detailed guide: docs/STDIO_MODE.md

Architecture

Transport Modes

This server supports three transport modes:

1. stdio (Standard I/O) - ⭐ Recommended for personal use

   • Simple setup, stable, secure
   • Perfect for local/personal use
   • 📘 Complete stdio guide

2. HTTP (Streamable HTTP) - ⭐ Recommended for team/VM deployment

   • Modern MCP protocol (2025-03-26)
   • Central server deployment
   • Multi-user support with authentication
   • 📘 HTTP deployment guide

MCP Capabilities

1. Tools: Functions to interact with Notion API
2. Resources: Access to Notion pages and databases
3. Authentication: Per-user API key management

Prerequisites

• Node.js 18+ or Node.js 20+
• A Notion account with API access
• Notion Integration created in Notion workspace

Installation

Option 1: Local Installation

# Clone the repository
git clone <repository-url>
cd notion-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Option 2: VM/Server Deployment (stdio mode)

For deploying on a VM where multiple users will connect via SSH:

# On your VM
git clone <repository-url>
cd notion-mcp-server
npm install
npm run build

# Start the server (stdio mode)
npm start

Option 3: HTTP Server Deployment (Recommended for VMs)

For a true central server with Streamable HTTP:

# On your VM
git clone <repository-url>
cd notion-mcp-server
npm install
npm run build

# Start HTTP server
npm run start:http

# Or with PM2 for production
npm install -g pm2
pm2 start dist/index-http.js --name notion-mcp-http
pm2 save

📘 See docs/HTTP_MODE.md for complete HTTP setup guide

Getting Your Notion API Key

1. Go to https://www.notion.so/my-integrations
2. Click "+ New integration"
3. Give it a name (e.g., "Claude Code Integration")
4. Select the workspace you want to connect
5. Click "Submit"
6. Copy the "Internal Integration Token" - this is your API key
7. Important: Share the integration with the pages/databases you want to access:
   • Open the page in Notion
   • Click "..." menu → "Add connections"
   • Select your integration

Claude Code Configuration

stdio Mode (Recommended)

The simplest and most reliable way to use this server:

claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=secret_your_notion_key \
  --env USER_ID=optional_user_id \
  -- node /absolute/path/to/notion-mcp-server/dist/index.js

Windows Example:

claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=ntn_xxxxxxxxxx \
  -- node C:/IdeaProject/mcp/notion-mcp-server/dist/index.js

Mac/Linux Example:

claude mcp add --transport stdio notion \
  --env NOTION_API_KEY=ntn_xxxxxxxxxx \
  -- node /Users/username/notion-mcp-server/dist/index.js

Verify:

claude mcp list
# Should show: notion: node ... - ✓ Connected

📘 Full stdio guide: docs/STDIO_MODE.md

Claude Desktop App Configuration

For Claude Desktop (not CLI), edit the config file:

Mac/Linux: ~/.claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/notion-mcp-server/dist/index.js"],
      "env": {
        "NOTION_API_KEY": "secret_your_notion_key"
      }
    }
  }
}

Advanced: HTTP Mode (Team Deployment)

For teams or remote deployment, see docs/HTTP_MODE.md

First, register with the HTTP server:

curl -X POST http://your-server:3000/register \
  -H "Content-Type: application/json" \
  -d '{"notionApiKey": "secret_xxx"}'

Then connect with Claude Code:

claude mcp add --transport http notion \
  --header "X-User-Id: YOUR_USER_ID" \
  --header "X-Api-Key: YOUR_NOTION_KEY" \
  http://your-server:3000/mcp

Note: For production, use HTTPS with proper SSL certificates.

Method 3: NPM Package (Coming Soon)

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "your-notion-api-key",
        "USER_ID": "your-user-id"
      }
    }
  }
}

Available Tools

Once configured, Claude Code can use these tools:

1. search_pages

Search for Notion pages in your workspace.

{
  query: "project notes",
  page_size: 10
}

2. search_databases

Find Notion databases.

{
  query: "tasks",
  page_size: 10
}

3. get_page

Get details of a specific page.

{
  page_id: "page-id-here"
}

4. get_page_content

Read the content blocks of a page.

{
  page_id: "page-id-here"
}

5. create_page

Create a new page.

{
  parent: { page_id: "parent-page-id" },
  title: "New Page",
  content: [
    {
      object: "block",
      type: "paragraph",
      paragraph: {
        rich_text: [{ type: "text", text: { content: "Hello!" } }]
      }
    }
  ]
}

6. append_blocks

Add content to an existing page.

{
  page_id: "page-id-here",
  blocks: [/* block objects */]
}

7. query_database

Query a database with filters.

{
  database_id: "database-id-here",
  filter: {
    property: "Status",
    select: { equals: "In Progress" }
  }
}

8. get_database

Get database schema and properties.

{
  database_id: "database-id-here"
}

Security Considerations

• API keys are hashed using SHA-256 before storage
• Each user has a unique ID for authentication
• Keys are never logged or exposed in responses
• Store users.json securely and backup regularly
• Use environment variables for sensitive data
• Consider using HTTPS for remote deployments

Development

# Run in development mode with auto-reload
npm run dev

# Build
npm run build

# Production
npm start

Troubleshooting

"Invalid Notion API key"

• Verify your API key is correct
• Check that the integration is shared with your pages
• Ensure the integration has the necessary permissions

"User not found"

• Make sure you've run the registration script
• Verify the User ID matches the one from registration

Claude Code can't connect

• Check that the path to index.js is absolute
• Verify Node.js is in your PATH
• Check Claude Code logs for errors

SSH connection issues (VM deployment)

• Ensure SSH key authentication is configured
• Test SSH connection manually first
• Check firewall rules on the VM

VM Deployment Best Practices

For production VM deployment:

1. Use a process manager (PM2, systemd):

npm install -g pm2
pm2 start dist/index.js --name notion-mcp-server
pm2 save

2. Set up automatic backups of users.json

3. Configure firewall to restrict access

4. Use SSH key authentication only (disable password auth)

5. Monitor logs:

pm2 logs notion-mcp-server

6. Keep the server updated:

git pull
npm install
npm run build
pm2 restart notion-mcp-server

API Reference

For detailed Notion API documentation, see: https://developers.notion.com/reference/intro

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

• Check the troubleshooting section
• Review Notion API documentation
• Open a GitHub issue