@debuggingmax/mcp-server-notion

<div align="center">

The most comprehensive MCP server for Notion 🚀

Pages • Databases • Blocks • Users • Comments • Search

Installation • Tools • Configuration • Examples • Pro Features

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

# 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

---

<div align="center">

Built with ❤️ for the Claude & Notion community

Report Bug • Request Feature

</div>