mirrorweb/notion-mcp-server-mw

Notion MCP Server

A comprehensive Model Context Protocol (MCP) server that provides secure, per-user Notion integration for AI development tools like Claude Desktop, Cline, and other MCP-compatible clients.

🚀 Features

17 Comprehensive Tools

🔍 Query & Search Tools

• execute-soql - Execute SOQL queries with auto-bulk switching and pagination
• execute-sosl - Multi-object search with result aggregation
• describe-sobject - SObject metadata with intelligent caching

⚡ Apex Development Tools

• execute-apex - Anonymous Apex execution with debug log capture
• run-apex-tests - Apex test execution with coverage reporting
• get-apex-logs - Debug log retrieval with filtering

📊 Data Management Tools

• create-record - Single/bulk record creation with auto-bulk switching
• get-record - Record retrieval with field selection
• update-record - Single/bulk record updates with validation
• delete-record - Single/bulk record deletion
• upsert-record - External ID-based upsert operations

🔧 Metadata Tools (Component-Based)

• list-metadata-types - Discover metadata types
• deploy-metadata - Deploy individual metadata components (e.g., ApexClass, CustomObject) from files or JSON
• deploy-bundle - Deploy a metadata bundle (e.g., LWC) from a directory path
• retrieve-metadata - Retrieve individual metadata components, with an option to save to a file
• check-deploy-status - Check the status of a deployment

🔗 Connection Tools

• test-connection - Connection validation and health monitoring

Key Capabilities

• 🔄 Auto-Bulk Switching - Intelligent API selection for optimal performance
• 🔐 Secure OAuth2 Authentication - Per-user access with individual limits and permissions
• ⚡ Smart Caching - 1-hour TTL for SObject metadata
• 🛡️ Type Safety - Full TypeScript implementation with runtime validation
• 📝 Comprehensive Logging - Detailed debugging and monitoring
• 🔍 Raw Error Exposure - Preserve exact Notion errors for debugging

🔐 Authentication Setup

This server uses OAuth2 authentication for secure, per-user access to Notion. This approach ensures individual user access limits and proper security compliance.

⚠️ Security Notice: Username/password authentication is deprecated for security reasons. OAuth2 provides better security, individual user tracking, and respects organizational access policies.

Step 1: Create a Connected App in Notion

1. Navigate to Setup:

   • Log into your Notion org
   • Go to Setup → App Manager
   • Click New Connected App

2. Basic Information:

   Connected App Name: MCP Notion Server
   API Name: MCP_Notion_Server
   Contact Email: your-email@company.com
   

3. API (Enable OAuth Settings):

   • Check Enable OAuth Settings
   • Callback URL: http://localhost:3000/callback (for local development)
   • Selected OAuth Scopes:
     • Access and manage your data (api)
     • Perform requests on your behalf at any time (refresh_token, offline_access)
     • Access your basic information (id, profile, email, address, phone)

4. Additional Settings:

   • Require Secret for Web Server Flow: Checked
   • Require Secret for Refresh Token Flow: Checked
   • Enable Client Credentials Flow: Unchecked (not needed)

5. Save and Note Credentials:

   • After saving, note the Consumer Key (Client ID)
   • Click Click to reveal for the Consumer Secret (Client Secret)

Step 2: Obtain Refresh Token

You need to complete the OAuth2 authorization code flow to get a refresh token. Here are several methods:

Method 1: Using Notion CLI (Recommended)

# Install Notion CLI if not already installed
npm install -g @notion/cli

# Authorize your org (this will open a browser)
sf org login web --set-default-dev-hub --alias my-org

# Get the refresh token
sf org display --verbose --target-org my-org

Method 2: Using Browser (Manual Flow)

1. Authorization URL:

   https://login.notion.com/services/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback&scope=api%20refresh_token
   

   Replace YOUR_CLIENT_ID with your Connected App's Consumer Key.

2. Complete Authorization:

   • Open the URL in your browser
   • Log in and approve the app
   • You'll be redirected to http://localhost:3000/callback?code=AUTHORIZATION_CODE
   • Copy the code parameter value

3. Exchange Code for Tokens:

   curl -X POST https://login.notion.com/services/oauth2/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=http://localhost:3000/callback" \
     -d "code=YOUR_AUTHORIZATION_CODE"
   

4. Extract Refresh Token: From the JSON response, save the refresh_token value.

Method 3: Using Postman

1. Create a new POST request to: https://login.notion.com/services/oauth2/token
2. Set headers: Content-Type: application/x-www-form-urlencoded
3. In the body (x-www-form-urlencoded), add:

   grant_type: authorization_code
   client_id: YOUR_CLIENT_ID
   client_secret: YOUR_CLIENT_SECRET
   redirect_uri: http://localhost:3000/callback
   code: YOUR_AUTHORIZATION_CODE
   

Step 3: Configure MCP Client

For Production Orgs:

• Instance URL: https://yourcompany.my.notion.com
• Login URL: Use the instance URL above

For Sandbox Orgs:

• Instance URL: https://yourcompany--sandbox.sandbox.my.notion.com
• Login URL: Replace with your sandbox instance URL

🚀 Installation

On macOS / Linux systems:

{
  "mcp.servers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@jjar/notion-mcp-server"
      ],
      "env": {
        "NOTION_CLIENT_ID": "your-oauth2-client-id",
        "NOTION_CLIENT_SECRET": "your-oauth2-client-secret", 
        "NOTION_REFRESH_TOKEN": "your-refresh-token",
        "NOTION_INSTANCE_URL": "https://yourorg.my.notion.com",
        
        // Optional: Enable Enterprise optimizations for Claude Enterprise accounts
        "NOTION_ENTERPRISE_MODE": "true",
        "NOTION_MAX_RESPONSE_SIZE": "75000",
        "NOTION_MAX_RECORDS_PER_RESPONSE": "300"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}

On Windows systems:

{
  "mcp.servers": {
    "notion": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@jjar/notion-mcp-server"
      ],
      "env": {
        "NOTION_CLIENT_ID": "your-oauth2-client-id",
        "NOTION_CLIENT_SECRET": "your-oauth2-client-secret", 
        "NOTION_REFRESH_TOKEN": "your-refresh-token",
        "NOTION_INSTANCE_URL": "https://yourorg.my.notion.com",
        
        // Optional: Enable Enterprise optimizations for Claude Enterprise accounts
        "NOTION_ENTERPRISE_MODE": "true",
        "NOTION_MAX_RESPONSE_SIZE": "75000",
        "NOTION_MAX_RECORDS_PER_RESPONSE": "300"
      },
      "disabled": false,
      "alwaysAllow": [
        "test-connection",
        "execute-soql",
        "describe-sobject",
        "get-record",
        "get-apex-logs",
        "list-metadata-types"
      ]
    }
  }
}

Configuration File Locations

🏢 Enterprise Configuration

For Claude Enterprise accounts with 200K+ token context windows, this MCP server includes specialized optimizations to maximize data throughput while preventing context overflow.

Enterprise Benefits

• 75K character responses (vs 4K standard) - 18x larger responses
• 300 records per response (vs 25-50 standard) - 6-12x more data
• Intelligent response optimization - Automatic size management for Enterprise context windows
• Enhanced bulk operations - Higher thresholds for bulk API usage
• Auto-aggregation support - Intelligent data consolidation for complex queries

Enable Enterprise Mode

Add these environment variables to your MCP configuration:

{
  "mcp.servers": {
    "notion": {
      "env": {
        "NOTION_CLIENT_ID": "your-oauth2-client-id",
        "NOTION_REFRESH_TOKEN": "your-refresh-token", 
        "NOTION_INSTANCE_URL": "https://yourorg.my.notion.com",
        
        // Enterprise Optimization
        "NOTION_ENTERPRISE_MODE": "true",
        "NOTION_MAX_RESPONSE_SIZE": "75000",
        "NOTION_MAX_RECORDS_PER_RESPONSE": "300",
        "NOTION_BULK_QUERY_THRESHOLD": "5000",
        "NOTION_BULK_DML_THRESHOLD": "500",
        "NOTION_ENABLE_AUTO_AGGREGATION": "true"
      }
    }
  }
}

Enterprise Response Optimization

When Enterprise mode is enabled:

• Smart Record Limiting: Automatically balances record count vs response size
• Context Window Monitoring: Real-time estimation of context usage
• Priority Field Optimization: Configurable field prioritization for large objects
• Bulk API Intelligence: Higher thresholds trigger bulk operations earlier
• Response Metadata: Detailed optimization information included in responses

Performance Characteristics

Enterprise Features in Action

// Enterprise mode automatically optimizes responses:
{
  "records": [...], // Up to 300 records
  "totalDisplayed": 300,
  "totalOriginal": 1500,
  "truncated": true,
  "truncationReason": "Limited to 300 records for Enterprise context optimization",
  "contextWindowUsage": "~65,000 chars (~16,250 tokens)",
  "_enterpriseOptimization": {
    "enabled": true,
    "contextOptimized": "Optimized for Claude Enterprise 200K+ context window"
  }
}

🔧 Environment Variables

Enterprise Environment Variables

Benefits of OAuth2 Authentication

1. Individual User Access: Each user authenticates with their own credentials
2. Granular Permissions: Respects user permissions and organizational policies
3. Audit Trail: All actions are tracked under the specific user
4. Security Compliance: Meets enterprise security requirements
5. Token Management: Refresh tokens can be revoked if compromised
6. No Password Exposure: Passwords are never stored or transmitted

🔒 Read-Only Mode (Default)

By default, the server runs in read-only mode for enhanced security. This means:

• ✅ Allowed: Query data, describe objects, retrieve metadata, get debug logs
• ❌ Blocked: Create, update, delete records, execute Apex, deploy metadata

Enabling Write Operations

To enable write operations, set the NOTION_ALLOW_WRITE environment variable:

NOTION_ALLOW_WRITE=true

Write operations include:

• create-record, update-record, delete-record, upsert-record
• execute-apex, run-apex-tests
• deploy-metadata, deploy-bundle

Security Considerations

• Read-only mode prevents accidental data modification
• Ideal for analytics, reporting, and development environments
• Enable write operations only when necessary and with appropriate user permissions
• All write operations still respect Notion user permissions and organizational policies

🛡️ Tool Safety Levels

✅ Safe for Auto-Approval (alwaysAllow)

• test-connection - Connection validation (read-only)
• execute-soql - SOQL queries (read-only)
• describe-sobject - Metadata inspection (read-only)
• get-record - Single record retrieval (read-only)
• get-apex-logs - Debug log access (read-only)
• list-metadata-types - Metadata type discovery (read-only)

⚠️ Requires Manual Approval

• create-record, update-record, delete-record, upsert-record - Data modification
• deploy-metadata - Metadata deployment
• execute-apex, run-apex-tests - Code execution
• execute-sosl - Search operations (can be resource-intensive)
• retrieve-metadata - Metadata retrieval (can be large)

🔍 Troubleshooting

Common OAuth Issues

1. Invalid Client ID/Secret:

   • Verify the Connected App credentials
   • Ensure the app is deployed and active

2. Invalid Refresh Token:

   • Re-generate the refresh token using the authorization flow
   • Check token expiration in Connected App settings

3. Instance URL Mismatch:

   • Use the exact instance URL from your Notion org
   • For sandboxes, include the full sandbox URL

4. Permission Issues:

   • Verify OAuth scopes in the Connected App
   • Check user permissions for specific operations

Testing Your Configuration

Use the test-connection tool to verify your setup:

# The MCP server will use this tool automatically when you ask about connection status
# Example: "Test my Notion connection"

🏗️ Architecture

Core Components

• OAuth2 Authentication Manager - Secure token-based authentication
• Connection Manager - Singleton pattern with health monitoring
• Tool Classes - Organized by functionality (Query, Apex, Data, Metadata)
• Error Handler - Comprehensive error formatting with context
• Cache Manager - TTL-based caching for performance optimization

Performance Features

• Auto-Bulk Switching - Automatically uses Bulk API for large operations
• Intelligent Caching - SObject metadata cached for 1 hour
• Connection Reuse - Single connection across all operations
• Polling Optimization - Efficient monitoring of long-running operations

🧪 Testing

# Test individual tools
node tests/test-query-tools.js
node tests/test-data-tools.js
node tests/test-apex-tools.js
node tests/test-metadata-tools.js

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🔗 Related Projects

• Model Context Protocol - The protocol this server implements
• jsforce - Notion API library used in this project
• Claude Desktop - AI assistant that supports MCP servers
• Cline - VS Code extension for AI-assisted development

👨‍💻 Author

Jarosław Jaworski

🤖 Development Credits

Part of this implementation was developed with assistance from Claude Sonnet 4 using the Cline VS Code extension, demonstrating the power of AI-assisted development in creating comprehensive developer tools.

📄 License

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

🚀 Kandji Deployment

This project includes automated deployment to Kandji MDM for macOS environments. The deployment workflow automatically uploads PKG installers to Kandji when releases are published.

Prerequisites

Configure the following GitHub Secrets:

• MW_KANDJI_API_TOKEN - Kandji API token (Settings > Integrations > API Token)
• MW_KANDJI_API_URL - Kandji API URL (e.g., https://<tenant>.api.kandji.io)
• MW_SLACK_BOT_TOKEN (optional) - Slack bot token for deployment notifications

Automatic Deployment

The workflow triggers automatically when:

• A GitHub release is published
• Manual trigger via workflow_dispatch

Manual Deployment

To deploy a specific release to Kandji:

1. Go to the Actions tab in GitHub
2. Select "Push PKG to Kandji" workflow
3. Click "Run workflow"
4. Configure options:
   • Release tag: Specific version (e.g., v1.1.0) or leave empty for latest
   • App name: Custom name for Kandji (default: "Notion MCP Server")
   • Enforcement: Deployment policy (install_and_enforce, install_once, or self_service)
   • Category: Self-service category (default: "Productivity")

Deployment Features

• 📦 Automatic PKG Download - Retrieves signed PKG from GitHub releases
• 🔄 Dynamic Lookup - Updates existing Kandji Custom Apps or creates new ones
• 🛡️ Version Management - Follows NAME-VERSION.pkg naming convention
• 📱 Slack Notifications - Optional deployment success notifications
• 🔍 Validation - PKG signature verification and integrity checks

Kandji Configuration

After deployment:

1. New Custom Apps: Must be manually assigned to Blueprints in Kandji
2. Updated Apps: Retain existing Blueprint assignments
3. Enforcement Policies: Configured via workflow parameters
4. Self-Service Categories: Organized for end-user discovery

Troubleshooting

• HTTP 503 Errors: kpkg automatically retries with delays
• Version Conflicts: Use dynamic lookup to update existing apps
• Blueprint Assignment: New apps require manual Blueprint configuration in Kandji
• Quarantine Issues: Workflow automatically clears quarantine attributes

For detailed logs, check the GitHub Actions workflow run output.

🔄 Automated Release System

This project features a fully automated release system that ensures consistent versioning and seamless deployment:

Automatic Releases

When you update package.json version (in a commit to master):

1. 🤖 Auto-release workflow detects version changes
2. 🏷️ Creates GitHub release with proper tag
3. 📦 Triggers build workflow to create PKG installer
4. 🚀 Deploys to Kandji automatically (5-minute delay for build completion)

Manual Version Management

# Bump version and trigger automated release
./scripts/bump-version.sh patch   # 1.1.2 → 1.1.3
./scripts/bump-version.sh minor   # 1.1.2 → 1.2.0  
./scripts/bump-version.sh major   # 1.1.2 → 2.0.0

# Fix current version situation (create missing release)
./scripts/create-missing-release.sh

# Sync versions across all files manually
./scripts/sync-version.sh [version]

Release Workflow Features

• 🔍 Version Detection - Automatic detection of package.json changes
• 📝 Auto-Generated Release Notes - Dynamic release content based on version
• 🏗️ PKG Build Integration - Seamless integration with existing build workflow
• ⚙️ Kandji Auto-Deployment - Automatic MDM deployment after successful build
• 🔄 Version Synchronization - Keeps all files in sync (package.json, Xcode, etc.)

Version Consistency

The system maintains version consistency across:

• 📄 package.json - Primary version source
• 🔒 package-lock.json - Automatically synced
• 💻 src/index.ts - Server version reporting
• 🍎 Xcode project MARKETING_VERSION - macOS app versioning
• 🏷️ Git tags - Release tagging
• 📝 GitHub release notes - Dynamic version references

Current Status: v1.1.2

We're currently transitioning to this automated system. The project is at v1.1.2 in package.json, with automated workflows in place for future releases.

📚 Documentation

Complete documentation is available in the directory:

• 🚀 - OAuth 2.0 configuration
• 🚢 - Installation and packaging
• 🛠️ - Technical implementation guides
• 📖 - Usage examples and patterns
• 🔧 - Issue resolution guides

👉 Start with the for a complete overview.