Notion MCP Connection¶

Overview¶

The Notion Model Context Protocol (MCP) server enables natural language interaction with Notion workspaces, databases, pages, and content through WorkBuddy. This remote MCP server allows AI assistants to query, create, and update Notion content seamlessly.

Key Features: - Database querying and filtering - Page creation and content management - Property updates and relational data handling - Template application and page organization - Team knowledge base management

Connection Type¶

Remote MCP Server – Connects to Notion's hosted MCP endpoint at https://mcp.notion.com/mcp

Prerequisites¶

Notion Account: A Notion account with workspace access
Notion Integration: An internal integration created in Notion (requires admin access)
Integration Token: API token from your Notion integration
Database Permissions: Integration must be invited to relevant databases/pages
Network Access: Ability to reach https://mcp.notion.com/
WorkBuddy: Desktop version with MCP support enabled

Configuration¶

1. Create Notion Integration¶

Go to Notion Integrations
Click "New integration"
Name your integration (e.g., "WorkBuddy MCP")
Select the workspace where it will be used
Configure capabilities (recommended: "Read content", "Update content", "Insert content")
Copy the "Internal Integration Token" (starts with secret_)

For each database or page you want to access: 1. Open the database/page 2. Click "Share" in the top-right 3. Invite your integration by name 4. Set appropriate permissions (Can edit, Can comment, or Can view)

3. MCP Server Registration¶

Update your WorkBuddy MCP configuration (~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp",
      "env": {
        "NOTION_API_KEY": "your_integration_token_here"
      }
    }
  }
}

4. Set Environment Variable¶

Replace your_integration_token_here with your actual Notion integration token (starts with secret_):

"env": {
  "NOTION_API_KEY": "secret_your_token_here"
}

Security Note: Store the token in an environment variable rather than hardcoding in mcp.json for production use.

5. Verify Connection¶

After updating mcp.json and restarting WorkBuddy (or reloading MCP servers), test the connection:

User: "List my Notion databases"
Assistant: (Lists databases accessible to the integration)

Usage Examples¶

Database Operations¶

User: "Show me all tasks due this week from the project tracker"
Assistant: (Queries database with date filter, returns formatted results)

User: "Add a new customer entry to the CRM database"
Assistant: (Creates new database entry with specified properties)

User: "Update the status of task 'Design review' to 'Completed'"
Assistant: (Finds and updates the specified page)

Content Management¶

User: "Create a new meeting notes page in the team workspace"
Assistant: (Creates page with template structure)

User: "Find all pages mentioning 'Q2 planning'"
Assistant: (Searches across workspace, returns matching pages)

User: "Add the 'Priority' property to the project database"
Assistant: (Modifies database schema if permissions allow)

Knowledge Base Management¶

User: "Summarize the team meeting notes from last week"
Assistant: (Extracts and summarizes content from multiple pages)

User: "Create a table of contents for the onboarding documentation"
Assistant: (Generates structured TOC based on page hierarchy)

Supported Operations¶

Operation	Description	Required Permissions
Database Query	Query databases with filters, sorts	Read content
Page Read	Read page content and properties	Read content
Page Create	Create new pages or database entries	Insert content
Page Update	Update page content and properties	Update content
Database Schema	Read/update database properties	Update content
Search	Search across workspace	Read content

Property Type Support¶

The Notion MCP server supports Notion's property types:

Property Type	Supported Operations	Notes
Title	Read/Write	Primary page title
Text/Rich Text	Read/Write	Markdown support
Number	Read/Write	Integer and decimal
Select	Read/Write	Single/multi-select options
Status	Read/Write	Status property
Date	Read/Write	Dates and date ranges
Person	Read/Write	User mentions
Files & Media	Read	Media attachments
Checkbox	Read/Write	Boolean values
URL	Read/Write	Links
Email	Read/Write	Email addresses
Phone	Read/Write	Phone numbers
Formula	Read only	Calculated values
Relation	Read/Write	Relations between databases
Rollup	Read only	Rollup calculations

Troubleshooting¶

Common Issues¶

Unauthorized Access

Error: Notion API error 401 - Unauthorized

Verify integration token is correct
Check that integration is invited to the database/page
Ensure token hasn't been revoked

Database Not Found

Error: Database not found or inaccessible

Share database with the integration
Verify database ID is correct
Check workspace permissions
Rate Limiting
```
Error: Rate limit exceeded
```
Notion API has rate limits (typically 3 requests per second)
Implement retry logic with exponential backoff
Cache frequently accessed data

Debug Mode¶

Enable debug logging in MCP configuration:

"env": {
  "NOTION_API_KEY": "your_token",
  "NOTION_LOG_LEVEL": "DEBUG"
}

Security Considerations¶

Integration Tokens¶

Use dedicated integrations for different security contexts
Regularly rotate integration tokens
Store tokens in secure environment variable stores
Never commit tokens to version control

Permission Scoping¶

Grant minimal necessary permissions (start with "Read content")
Use different integrations for different privilege levels
Regularly audit integration access

Data Sensitivity¶

Consider data classification before exposing via MCP
Implement additional filtering for sensitive databases
Use Notion's page-level permissions for sensitive content

Performance Optimization¶

Query Optimization¶

Use specific filters to limit result sets
Request only needed properties
Cache database schemas and page structures
Implement pagination for large datasets

Batch Operations¶

Group related updates into batches
Use Notion's batch update capabilities where available
Schedule non-urgent updates during off-peak times

Integration Patterns¶

Project Management¶

Sync tasks between Notion and other tools (GitHub, Jira)
Generate status reports from project databases
Automate milestone tracking and notifications

Documentation Workflows¶

Auto-generate documentation from code comments
Sync meeting notes with calendar events
Create knowledge base articles from support tickets

Team Collaboration¶

Onboarding checklists and progress tracking
Team directory and skill inventory
Resource library management

Notion API Documentation
Notion Integrations Guide
Canonical MCP Structures – Standardized setup patterns
WorkBuddy Notion Skill – Additional Notion capabilities

Support¶

Notion Support¶

WorkBuddy Support¶

WorkBuddy logs for MCP connection issues
Organization platform team for internal support
WorkBuddy Documentation

Last Updated: 2026‑05‑19
Maintainer: Platform Team
Connection Type: Remote MCP Server
Authentication: Notion Integration Token
Status: 🔧 Configuration Required