# @suncreation/mcp-notion-server

MCP Server for the Notion API, enabling LLM to interact with Notion workspaces.

> **Fork Notice**: This is a fork of [@suekou/mcp-notion-server](https://github.com/suekou/mcp-notion-server) with enhancements including improved error handling, additional features, and better environment variable support.

## Features

- Full Notion API integration via MCP (Model Context Protocol)
- Markdown conversion to reduce token usage
- **Page creation** (`notion_create_page`) - Create new pages under existing pages
- Supports both `NOTION_API_TOKEN` and `NOTION_API_KEY` environment variables
- Enhanced error handling with detailed HTTP status code messages

## Installation

```bash
npx -y @suncreation/mcp-notion-server
```

## Quick Start

### 1. Create a Notion Integration

1. Visit the [Notion Integrations page](https://www.notion.so/profile/integrations)
2. Click **"New Integration"**
3. Name your integration and select permissions:
   - ✅ Read content
   - ✅ Update content
   - ✅ Insert content
4. Copy the **"Internal Integration Token"** (starts with `ntn_` or `secret_`)

### 2. Connect Integration to Pages

1. Open the Notion page you want to access
2. Click **"···"** (top right) → **"Connections"**
3. Add your integration

### 3. Configure Your MCP Client

#### OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "notion": {
      "type": "local",
      "command": ["npx", "-y", "@suncreation/mcp-notion-server"],
      "environment": {
        "NOTION_API_TOKEN": "your-integration-token"
      },
      "enabled": true
    }
  }
}
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suncreation/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}
```

#### Multiple Workspaces

You can connect multiple Notion workspaces by using different names:

```json
{
  "mcp": {
    "notion-work": {
      "type": "local",
      "command": ["npx", "-y", "@suncreation/mcp-notion-server"],
      "environment": {
        "NOTION_API_TOKEN": "work-workspace-token"
      },
      "enabled": true
    },
    "notion-personal": {
      "type": "local",
      "command": ["npx", "-y", "@suncreation/mcp-notion-server"],
      "environment": {
        "NOTION_API_TOKEN": "personal-workspace-token"
      },
      "enabled": true
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NOTION_API_TOKEN` | Yes* | Your Notion API integration token |
| `NOTION_API_KEY` | Yes* | Alternative name for the token (either works) |
| `NOTION_MARKDOWN_CONVERSION` | No | Set to `"true"` for Markdown output (reduces tokens) |

*One of `NOTION_API_TOKEN` or `NOTION_API_KEY` is required.

## Available Tools

### Pages
| Tool | Description |
|------|-------------|
| `notion_retrieve_page` | Get page information |
| `notion_update_page_properties` | Update page properties |
| `notion_create_page` | **Create a new page** (enhanced feature) |

### Blocks
| Tool | Description |
|------|-------------|
| `notion_retrieve_block` | Get block information |
| `notion_retrieve_block_children` | Get child blocks |
| `notion_append_block_children` | Add blocks to a page/block |
| `notion_delete_block` | Delete a block |

### Databases
| Tool | Description |
|------|-------------|
| `notion_create_database` | Create a new database |
| `notion_query_database` | Query database entries |
| `notion_retrieve_database` | Get database schema |
| `notion_update_database` | Update database properties |
| `notion_create_database_item` | Add item to database |

### Search & Users
| Tool | Description |
|------|-------------|
| `notion_search` | Search pages/databases by title |
| `notion_list_all_users` | List workspace users (Enterprise) |
| `notion_retrieve_user` | Get user details (Enterprise) |
| `notion_retrieve_bot_user` | Get bot user info |

### Comments
| Tool | Description |
|------|-------------|
| `notion_create_comment` | Add a comment |
| `notion_retrieve_comments` | Get comments on a page/block |

## Command Line Options

```bash
# Enable only specific tools
node build/index.js --enabledTools=notion_retrieve_page,notion_query_database

# Read-only mode example
node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search
```

## Markdown Conversion

Enable Markdown conversion for reduced token usage:

```json
{
  "environment": {
    "NOTION_API_TOKEN": "your-token",
    "NOTION_MARKDOWN_CONVERSION": "true"
  }
}
```

- Use `format: "markdown"` for readable output (viewing)
- Use `format: "json"` for structured data (editing)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Permission denied | Ensure integration is added to the page via "Connections" |
| 401 Unauthorized | Check your API token is correct |
| 404 Not Found | Verify the page/database ID is correct |
| Rate limited | Add delays between requests |

## Development

```bash
# Clone and install
git clone https://github.com/SunCreation/mcp-notion-server.git
cd mcp-notion-server
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run watch
```

## Changes from Original

This fork includes the following enhancements over [@suekou/mcp-notion-server](https://github.com/suekou/mcp-notion-server):

1. **`notion_create_page` tool** - Create new pages under existing pages
2. **Dual environment variable support** - Both `NOTION_API_TOKEN` and `NOTION_API_KEY` work
3. **Enhanced error handling** - Detailed HTTP status code messages for easier debugging
4. **`setApiVersion()` method** - Dynamically change API version if needed

## License

MIT License - see [LICENSE](LICENSE) file.

## Credits

- Original project: [@suekou/mcp-notion-server](https://github.com/suekou/mcp-notion-server)
- Setup guides: [English](https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h) | [Japanese](https://qiita.com/suekou/items/44c864583f5e3e6325d9)