# @debuggingmax/mcp-server-notion

<div align="center">

[![npm version](https://img.shields.io/npm/v/@debuggingmax/mcp-server-notion.svg)](https://www.npmjs.com/package/@debuggingmax/mcp-server-notion)
[![npm downloads](https://img.shields.io/npm/dm/@debuggingmax/mcp-server-notion.svg)](https://www.npmjs.com/package/@debuggingmax/mcp-server-notion)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink)](https://github.com/sponsors/DebuggingMax)

**The most comprehensive MCP server for Notion** 🚀

*Pages • Databases • Blocks • Users • Comments • Search*

[Installation](#-quick-install) • [Tools](#-available-tools) • [Configuration](#%EF%B8%8F-configuration) • [Examples](#-examples) • [Pro Features](#-pro--enterprise)

</div>

---

## ✨ Features

- **22 Tools** covering the entire Notion API
- **Full CRUD** for Pages, Databases, and Blocks
- **Advanced Filtering** with Notion's powerful query syntax
- **Rich Text Support** for all content types
- **Pagination** for large datasets
- **Comments & Discussions** support
- **User Management** including bot info
- **Type-Safe** with full TypeScript support

## 📦 Quick Install

```bash
# Using npx (no installation required)
npx @debuggingmax/mcp-server-notion

# Global installation
npm install -g @debuggingmax/mcp-server-notion

# As a dependency
npm install @debuggingmax/mcp-server-notion
```

## ⚙️ Configuration

### 1. Get Your Notion API Key

1. Go to [notion.so/my-integrations](https://www.notion.so/my-integrations)
2. Create a new integration
3. Copy the "Internal Integration Token"
4. Share your pages/databases with the integration

### 2. Configure Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@debuggingmax/mcp-server-notion"],
      "env": {
        "NOTION_API_KEY": "secret_your_api_key_here"
      }
    }
  }
}
```

### 3. Alternative: Environment Variable

```bash
export NOTION_API_KEY="secret_your_api_key_here"
npx @debuggingmax/mcp-server-notion
```

## 🛠 Available Tools

### 📄 Pages (6 tools)

| Tool | Description |
|------|-------------|
| `notion_search_pages` | Search pages by title |
| `notion_get_page` | Get page by ID with all properties |
| `notion_create_page` | Create page in database or as child page |
| `notion_update_page` | Update properties, icon, cover |
| `notion_archive_page` | Soft-delete (archive) a page |
| `notion_restore_page` | Restore archived page |

### 🗄 Databases (4 tools)

| Tool | Description |
|------|-------------|
| `notion_query_database` | Query with filters, sorts, pagination |
| `notion_get_database` | Get schema and properties |
| `notion_create_database` | Create with custom schema |
| `notion_update_database` | Update title, description, properties |

### 📦 Blocks (5 tools)

| Tool | Description |
|------|-------------|
| `notion_get_block_children` | Get all child blocks |
| `notion_append_blocks` | Add new content blocks |
| `notion_get_block` | Get specific block |
| `notion_update_block` | Modify block content |
| `notion_delete_block` | Remove block from page |

### 👥 Users (3 tools)

| Tool | Description |
|------|-------------|
| `notion_list_users` | List all workspace users |
| `notion_get_user` | Get user by ID |
| `notion_get_current_user` | Get bot/integration info |

### 💬 Comments (2 tools)

| Tool | Description |
|------|-------------|
| `notion_list_comments` | Get comments on page/block |
| `notion_create_comment` | Add comment to page/discussion |

### 🔍 Search (1 tool)

| Tool | Description |
|------|-------------|
| `notion_search` | Unified search across everything |

## 📖 Examples

### Search for Pages

```typescript
// Find pages containing "Project"
notion_search_pages({ query: "Project", page_size: 10 })
```

### Create a Task in Database

```typescript
notion_create_page({
  parent_type: "database",
  parent_id: "your-database-id",
  properties: {
    "Name": {
      "title": [{ "text": { "content": "New Task" } }]
    },
    "Status": {
      "select": { "name": "To Do" }
    },
    "Priority": {
      "select": { "name": "High" }
    }
  }
})
```

### Query Database with Filters

```typescript
notion_query_database({
  database_id: "your-database-id",
  filter: {
    "and": [
      {
        "property": "Status",
        "select": { "equals": "In Progress" }
      },
      {
        "property": "Priority",
        "select": { "equals": "High" }
      }
    ]
  },
  sorts: [
    { "property": "Due Date", "direction": "ascending" }
  ]
})
```

### Add Content to a Page

```typescript
notion_append_blocks({
  block_id: "page-id",
  children: [
    {
      "type": "heading_2",
      "heading_2": {
        "rich_text": [{ "text": { "content": "New Section" } }]
      }
    },
    {
      "type": "paragraph",
      "paragraph": {
        "rich_text": [{ "text": { "content": "This is the content." } }]
      }
    },
    {
      "type": "to_do",
      "to_do": {
        "rich_text": [{ "text": { "content": "Task item" } }],
        "checked": false
      }
    }
  ]
})
```

### Create a Comment

```typescript
notion_create_comment({
  parent_type: "page",
  parent_id: "page-id",
  rich_text: [
    { "text": { "content": "Great progress! 🎉" } }
  ]
})
```

## 🚀 Pro & Enterprise

**Coming Soon!** Pro features for power users:

- 📊 **Analytics Dashboard** - Usage stats, popular pages, activity insights
- ⚡ **Bulk Operations** - Update hundreds of pages at once
- 📋 **Templates** - Pre-built page and database templates
- 🔄 **Sync Tools** - Two-way sync with external systems
- 🔔 **Webhooks** - Real-time notifications on changes
- 🏢 **Enterprise SSO** - SAML/OIDC integration

Interested? [Contact us](https://github.com/DebuggingMax/mcp-server-notion/issues) or [sponsor the project](https://github.com/sponsors/DebuggingMax)!

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## 💖 Support

If this project helps you, consider:

- ⭐ **Starring** the repository
- 💝 **[Sponsoring](https://github.com/sponsors/DebuggingMax)** the development
- 🐛 **Reporting** bugs and issues
- 💡 **Suggesting** new features

## 📄 License

MIT © [DebuggingMax](https://github.com/DebuggingMax)

---

<div align="center">

**Built with ❤️ for the Claude & Notion community**

[Report Bug](https://github.com/DebuggingMax/mcp-server-notion/issues) • [Request Feature](https://github.com/DebuggingMax/mcp-server-notion/issues)

</div>