# 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)**:

```bash
# 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](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](docs/STDIO_MODE.md)**

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](docs/HTTP_MODE.md)**

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

```bash
# 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:

```bash
# 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:

```bash
# 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](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:

```bash
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`

```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](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)

```json
{
  "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.

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

### 2. `search_databases`
Find Notion databases.

```typescript
{
  query: "tasks",
  page_size: 10
}
```

### 3. `get_page`
Get details of a specific page.

```typescript
{
  page_id: "page-id-here"
}
```

### 4. `get_page_content`
Read the content blocks of a page.

```typescript
{
  page_id: "page-id-here"
}
```

### 5. `create_page`
Create a new page.

```typescript
{
  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.

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

### 7. `query_database`
Query a database with filters.

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

### 8. `get_database`
Get database schema and properties.

```typescript
{
  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

```bash
# 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):
```bash
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**:
```bash
pm2 logs notion-mcp-server
```

6. **Keep the server updated**:
```bash
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