Notion MCP Server

Notion MCP Server

What is Notion MCP Server about?

A server that exposes Notion workspace functionality (page search, read/write, comments, block operations, database creation and queries) as Model Context Protocol tools, allowing AI agents or other MCP‑compatible clients to manipulate Notion content programmatically.

How to use Notion MCP Server?

1. Clone the repository and install dependencies.
2. Set the NOTION_API_KEY environment variable with a Notion integration token.
3. Build the project (npm run build).
4. Run the server (e.g., via npx notion-server).
5. Configure your MCP client (Claude Desktop example) to point to the built index.js and supply the same API key.
6. Call the provided tools – search, read_page, create_page, update_page, create_database, query_database, etc. – from your AI or script.

Key features of Notion MCP Server

• Page Operations: search, read, create, update, comment, block‑level edit/delete.
• Rich Markdown Support: headings, code blocks, todo items, blockquotes, dividers, images, nested bullets.
• Database CRUD: create databases, add/update items, filter & sort queries.
• Broad Property Types: title, rich text, number, select, multi‑select, date, checkbox, and more.
• Straight‑forward Configuration: works with any MCP‑compatible client, example provided for Claude Desktop.
• MIT License and community‑friendly contribution guide.

Use cases of Notion MCP Server

• AI‑assisted knowledge bases: let a language model retrieve or update project documentation on demand.
• Automated meeting notes: generate pages from transcripts and tag them automatically.
• Task management bots: create, query, and move database items (e.g., Kanban boards) via natural‑language commands.
• Content publishing pipelines: programmatically produce formatted Notion pages from markdown sources.
• Comment moderation helpers: read and post comments to coordinate review cycles.

FAQ

Q: What Node version is required? A: Node.js v16 or higher.

Q: How do I obtain a Notion API key? A: Create an integration at https://www.notion.so/my-integrations, grant it the needed permissions, and copy the generated secret token.

Q: Do I need to share every page with the integration? A: Yes, each page or database you want the server to access must be connected to the integration via the Notion UI ("…" → "Connections").

Q: Can I run the server without building it first? A: For quick testing you can execute npx notion-server which will install and run the package directly.

Q: Is there support for other MCP clients besides Claude Desktop? A: Any client that follows the MCP specification can interact with the server; only the configuration JSON needs to reference the server command and environment variables.

Notion MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Notion. This server enables Language Models to interact with your Notion workspace through standardized tools for searching, reading, creating, and updating pages and databases.

🌟 Key Features

Page Operations

• 🔍 Search through your Notion workspace
• 📝 Create new pages with rich markdown content
• 📖 Read page content with clean formatting
• 🔄 Update existing pages
• 💬 Add and retrieve comments
• 🧱 Block-level operations (update, delete)

Enhanced Markdown Support

• Multiple heading levels (H1-H3)
• Code blocks with language support
• Interactive todo items with checkbox states
• Blockquotes with multi-line support
• Horizontal dividers
• Images with captions
• Nested bullet points

Database Operations

• Create and manage databases
• Add and update database items
• Query with filters and sorting
• Support for various property types:
  • Title, Rich text, Number
  • Select, Multi-select
  • Date, Checkbox
  • And more!

🚀 Getting Started

Prerequisites

• Node.js (v16 or higher)
• Notion API key
• MCP-compatible client (e.g., Claude Desktop)

Installation

1. Clone the repository:

git clone https://github.com/v-3/notion-server.git
cd notion-server

2. Install dependencies:

npm install

3. Set up your environment:

# Create .env file
echo "NOTION_API_KEY=your_notion_api_key_here" > .env

# Or export directly
export NOTION_API_KEY=your_notion_api_key_here

4. Build the server:

npm run build

🔧 Configuration

Claude Desktop Setup

1. Update your Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "notion": {
            "command": "node",
            "args": ["/absolute/path/to/notion-server/build/index.js"],
            "env": {
                "NOTION_API_KEY": "your_notion_api_key_here"
            }
        }
    }
}

2. Restart Claude Desktop to apply changes

🛠️ Available Tools

Page Operations

// Search pages
{
    query: string // Search query
}

// Read page
{
    pageId: string // ID of the page to read
}

// Create page
{
    title?: string,      // Page title
    content?: string,    // Page content in markdown
    parentPageId: string // Parent page ID
    properties?: object  // For database items
}

// Update page
{
    pageId: string,   // Page ID to update
    content: string,  // New content
    type?: string    // Content type
}

Database Operations

// Create database
{
    parentPageId: string,
    title: string,
    properties: object
}

// Query database
{
    databaseId: string,
    filter?: object,
    sort?: object
}

🔐 Setting Up Notion Access

Creating an Integration

1. Visit Notion Integrations
2. Click "New integration"
3. Configure permissions:
   • Content: Read, Update, Insert
   • Comments: Read, Create
   • User Information: Read

Connecting Pages

1. Open your Notion page
2. Click "..." menu → "Connections"
3. Add your integration
4. Repeat for other pages as needed

📝 Usage Examples

Creating a Page

const result = await notion.create_page({
  parentPageId: "page_id",
  title: "My Page",
  content: "# Welcome\nThis is a test page."
});

Querying a Database

const result = await notion.query_database({
  databaseId: "db_id",
  filter: {
    property: "Status",
    select: {
      equals: "In Progress"
    }
  }
});

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a Pull Request

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This project has been significantly improved by sweir1/notion-server, who has made following updates:

• Enhanced markdown support with more block types
• Comprehensive database operations
• Improved error handling and debugging
• Better property handling for database items
• Cleaner page output formatting

To use sweir1's version, you can clone their repository:

git clone https://github.com/sweir1/notion-server.git