@debuggingmax/mcp-server-notion

The most comprehensive MCP server for Notion 🚀

Pages • Databases • Blocks • Users • Comments • Search

Installation • Tools • Configuration • Examples • Pro Features

✨ 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

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

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

3. Alternative: Environment Variable

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

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

Create a Task in Database

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

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

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

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 or sponsor the project!

🤝 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 the development
• 🐛 Reporting bugs and issues
• 💡 Suggesting new features

📄 License

MIT © DebuggingMax

Built with ❤️ for the Claude & Notion community

Report Bug • Request Feature