Notion Advisor

An MCP (Model Context Protocol) server that provides AI assistants with full access to Notion workspaces. Enables Claude to search, read, create, and update pages, databases, and blocks.

Features

• Search & Discovery: Search across all pages and databases in your workspace
• Page Operations: Create, read, update, and archive pages
• Content Management: Add, update, and delete content blocks with markdown support
• Database Operations: Query databases with filters and sorts, create new databases
• User Management: List workspace users and get user details
• Rate Limiting: Built-in rate limiting to respect Notion API limits (3 req/sec)
• Markdown Conversion: Automatic conversion between markdown and Notion blocks

Installation

npm install -g @m2ai-mcp/notion-advisor

Or use directly with npx (no install required):

npx @m2ai-mcp/notion-advisor

Configuration

1. Create a Notion Integration

1. Go to Notion Integrations
2. Click "New integration"
3. Select "Internal integration"
4. Grant required capabilities:
   • Read content
   • Update content
   • Insert content
   • Read user information (optional)
5. Copy the "Internal Integration Token"

2. Share Content with Integration

For the integration to access pages and databases:

1. Open the page or database in Notion
2. Click the "..." menu in the top right
3. Click "Add connections"
4. Select your integration

3. Set Environment Variable

export NOTION_API_KEY=secret_your_integration_token_here

Or create a .env file:

NOTION_API_KEY=secret_your_integration_token_here

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["@m2ai-mcp/notion-advisor"],
      "env": {
        "NOTION_API_KEY": "secret_your_token_here"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "notion": {
      "command": "notion-advisor",
      "env": {
        "NOTION_API_KEY": "secret_your_token_here"
      }
    }
  }
}

Available Tools

Search & Discovery

| Tool | Description | |------|-------------| | search | Search across all pages and databases by keyword or title |

Page Operations

| Tool | Description | |------|-------------| | get_page | Retrieve a page's properties and metadata | | create_page | Create a new page in a database or as child of another page | | update_page | Update a page's properties (not content blocks) | | get_page_content | Retrieve all content blocks from a page |

Block Operations

| Tool | Description | |------|-------------| | append_blocks | Add new content blocks to a page (supports markdown) | | update_block | Update an existing block's content | | delete_block | Delete (archive) a block |

Database Operations

| Tool | Description | |------|-------------| | get_database | Retrieve database schema and properties | | query_database | Query a database with filters and sorts | | create_database | Create a new database as child of a page |

User Operations

| Tool | Description | |------|-------------| | list_users | List all users in the workspace | | get_user | Get details about a specific user |

Markdown Support

The server supports conversion of common markdown to Notion blocks:

• Headings (H1, H2, H3)
• Bold, italic, strikethrough, inline code
• Bullet and numbered lists
• Checkboxes / todo items
• Code blocks with language
• Links
• Blockquotes
• Horizontal rules

Example

# My Page Title

This is a paragraph with **bold** and *italic* text.

- Bullet item 1
- Bullet item 2

1. Numbered item
2. Another item

- [ ] Todo item
- [x] Completed item

> A blockquote

\`\`\`javascript
const greeting = "Hello, World!";
\`\`\`

Examples

Search for Pages

{
  "query": "meeting notes",
  "filter_type": "page",
  "page_size": 10
}

Create a Page in a Database

{
  "parent_id": "database-id-here",
  "parent_type": "database_id",
  "title": "New Task",
  "properties": {
    "Status": { "select": { "name": "In Progress" } }
  },
  "content": "## Task Description\n\nThis is the task content."
}

Query a Database

{
  "database_id": "database-id-here",
  "filter": {
    "property": "Status",
    "select": { "equals": "Done" }
  },
  "sorts": [
    { "property": "Due Date", "direction": "ascending" }
  ]
}

Append Content to a Page

{
  "parent_id": "page-id-here",
  "content": "## New Section\n\nAdding more content to this page.\n\n- Item 1\n- Item 2"
}

Known Limitations

• Cannot access pages not shared with the integration
• File/image uploads not supported (use URLs instead)
• Comments API limited
• Synced blocks are read-only

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

License

MIT

Author

Me, Myself Plus AI LLC