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:

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

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

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

Tools: Functions to interact with Notion API
Resources: Access to Notion pages and databases
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

Go to https://www.notion.so/my-integrations
Click "+ New integration"
Give it a name (e.g., "Claude Code Integration")
Select the workspace you want to connect
Click "Submit"
Copy the "Internal Integration Token" - this is your API key
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: ``bash 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: ``bash claude mcp add --transport stdio notion \ --env NOTION_API_KEY=ntn_xxxxxxxxxx \ -- node /Users/username/notion-mcp-server/dist/index.js ``

Verify: ```bash claude mcp list

Should show: notion: node ... - ✓ Connected


**📘 Full stdio guide: [docs/STDIO_MODE.md](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: ``bash curl -X POST http://your-server:3000/register \ -H "Content-Type: application/json" \ -d '{"notionApiKey": "secret_xxx"}' ``

Then connect with Claude Code: ``bash 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:

Use a process manager (PM2, systemd):

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

Set up automatic backups of users.json

Configure firewall to restrict access

Use SSH key authentication only (disable password auth)

Monitor logs:

pm2 logs notion-mcp-server

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

Notion MCP Server