Notion MCP Server: Setup, Troubleshooting & AI Meeting Notes

1 What is Notion MCP Server?

The Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI applications to securely connect with external data sources and tools. According to the official Notion MCP documentation, Notion's MCP implementation allows AI tools to interact with your workspace data through a standardized interface.

Key Capabilities

• Search Pages: Find pages and databases across your workspace by title or content
• Fetch Content: Retrieve full page content, including text, images, and embedded blocks
• Create Pages: Generate new pages with structured content
• Update Pages: Modify existing content, add comments, and manage properties
• Access Databases: Query database entries and filter results

Why Use MCP Instead of Direct API?

While Notion provides a comprehensive REST API, MCP offers several advantages for AI integration:

2 Remote vs Local MCP Server

Notion provides two ways to connect your workspace to AI tools via MCP. Understanding the difference is crucial for choosing the right approach for your use case.

3 Setup for Claude Code

Claude Code supports both remote and local MCP servers. According to the Notion MCP getting started guide, the setup process varies based on your preferred server type.

Option A: Remote MCP Server (Recommended)

First, add the Notion MCP server using the terminal command:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then complete the authentication flow:

You can specify installation scope when adding the server:

• --scope local (default): Available only in current project
• --scope project: Shared via .mcp.json file for team collaboration
• --scope user: Available across all your projects

# Example with user scope (available everywhere)
claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp

Option B: Local MCP Server

For the local server, you'll need to create a configuration file and set up authentication manually.

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "notion-local": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_YOUR_TOKEN_HERE"
      }
    }
  }
}

Additionally, create a .claude/settings.local.json file to enable the MCP server:

{
  "permissions": {
    "allow": [
      "mcp__notion__notion-search",
      "mcp__notion__notion-fetch",
      "mcp__notion-local__API-retrieve-a-block",
      "mcp__notion-local__API-get-block-children"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": [
    "notion-local"
  ]
}

4 Setup for Claude Desktop

Claude Desktop configuration differs slightly from Claude Code. Remote MCP servers are configured through the Settings UI, while local servers require editing the config file.

Remote MCP Setup

Remote MCP servers in Claude Desktop are configured through Settings → Connectors, not the config file. This is available on Pro, Max, Team, and Enterprise plans.

Local MCP Setup

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_TOKEN": "ntn_YOUR_TOKEN_HERE"
      }
    }
  }
}

Using mcp-remote Bridge

Some MCP clients only support local STDIO servers. You can still connect to the remote Notion MCP using the mcp-remote bridge:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]
    }
  }
}

5 Available MCP Tools

The Notion MCP Server provides several tools for interacting with your workspace. Understanding each tool's capabilities and limitations is essential for effective integration.

Official Notion MCP Tools

Self-Hosted MCP Tools (notion-local)

6 The AI Meeting Notes Problem

Notion's AI Meeting Notes feature automatically generates transcripts from recorded meetings. However, accessing these transcripts programmatically via the Notion API is blocked - a significant limitation for automation workflows.

The Core Issue

When you attempt to fetch a page containing AI Meeting Notes, the transcript sections return a placeholder instead of actual content:

<transcript>Transcript omitted from page content</transcript>

This isn't a bug or configuration issue - it's a deliberate limitation in Notion's API design. The transcription block type is explicitly unsupported.

What You See vs What You Get

Why This Matters

• Automation Blocked: Cannot automatically export meeting transcripts for CRM, project management, or documentation systems
• Search Limitations: AI Meeting Notes appear in search results but full content can't be retrieved
• Workflow Integration: Zapier, n8n, and other automation tools face the same limitation
• Archive Challenges: No programmatic way to backup or migrate meeting transcripts

7 Five Failed Approaches to Access Transcripts

Before discovering the citation extraction workaround, I tested multiple approaches to access meeting transcripts via the Notion API. Understanding why each approach fails helps explain the architecture of the eventual solution.

8 The Citation Extraction Workaround

After five failed approaches, I discovered a workaround that provides partial transcript access. The AI-generated summaries in Meeting Notes contain citation references that link to specific transcript segments - and these citations ARE accessible via the API.

How Citations Work

When Notion's AI generates a meeting summary, it cites specific portions of the transcript using this pattern:

The team discussed the architecture[^{{https://www.notion.so/page-id#block-id}}]

These citation URLs contain block IDs that point to individual paragraph blocks within the transcript. Unlike the transcription block itself, these paragraph blocks can be fetched via the Blocks API.

Extraction Process Flow

Critical Limitations

This workaround provides only partial transcript access. Understanding what you get vs what's missing is essential:

9 Python Extraction Script

Here's a complete Python implementation for extracting meeting transcripts using the citation extraction method. This script includes error handling, rate limiting, and completeness estimation.

Core Extraction Class

#!/usr/bin/env python3
"""
Notion Meeting Transcript Extractor

Extracts meeting transcripts from Notion AI Meeting Notes by fetching
citation blocks referenced in meeting summaries.

IMPORTANT LIMITATION:
This extracts ONLY the portions of transcripts that are cited in AI summaries.
Typical coverage is 40-95% of the full transcript.
"""

import os
import re
import json
import time
import requests
from pathlib import Path
from datetime import datetime
from collections import defaultdict
from typing import Optional, List, Dict, Tuple

# Configuration
NOTION_API_VERSION = "2022-06-28"
NOTION_BASE_URL = "https://api.notion.com/v1"
REQUEST_DELAY = 0.35  # seconds between requests (~3 req/sec limit)

# Completeness thresholds
EXPECTED_WORDS_PER_HOUR = 7200  # ~120 words/min speaking rate
LOW_COMPLETENESS_THRESHOLD = 50  # Mark as PARTIAL if below this %


class NotionTranscriptExtractor:
    def __init__(self, token: str, output_dir: str = "./Meetings"):
        self.token = token
        self.output_dir = Path(output_dir)
        self.output_dir.mkdir(exist_ok=True)
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Notion-Version": NOTION_API_VERSION,
            "Content-Type": "application/json"
        }
        self.session = requests.Session()
        self.session.headers.update(self.headers)
        self.request_count = 0

    def _format_block_id(self, block_id: str) -> str:
        """Format block ID with dashes (UUID format)."""
        clean_id = block_id.replace("-", "")
        if len(clean_id) == 32:
            return f"{clean_id[:8]}-{clean_id[8:12]}-{clean_id[12:16]}-{clean_id[16:20]}-{clean_id[20:]}"
        return block_id

    def fetch_block(self, block_id: str) -> Optional[dict]:
        """Fetch a block by ID using the Blocks API."""
        formatted_id = self._format_block_id(block_id)
        url = f"{NOTION_BASE_URL}/blocks/{formatted_id}"

        try:
            response = self.session.get(url)
            self.request_count += 1

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # Handle rate limiting
                retry_after = int(response.headers.get('Retry-After', 5))
                print(f"    Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                return self.fetch_block(block_id)  # Retry
            else:
                return None
        except Exception as e:
            print(f"    Exception fetching {block_id}: {e}")
            return None

    def extract_text_from_block(self, block: dict) -> str:
        """Extract plain text from a block's rich_text content."""
        if not block:
            return ""

        block_type = block.get("type", "")
        type_data = block.get(block_type, {})

        # Most transcript blocks are paragraphs
        if "rich_text" in type_data:
            rich_text = type_data["rich_text"]
            return "".join([rt.get("plain_text", "") for rt in rich_text])

        return ""

    def extract_citation_blocks_from_json(self, json_content: str) -> List[str]:
        """
        Extract citation block IDs from Notion MCP fetch output.
        Pattern: [^{{https://www.notion.so/page-id#block-id}}]
        """
        # Find all citation patterns
        pattern = r'notion.so/[a-f0-9-]+#([a-f0-9]+)'
        matches = re.findall(pattern, json_content)

        # Get unique block IDs while preserving order
        return list(dict.fromkeys(matches))

    def estimate_completeness(self, word_count: int) -> Tuple[int, str]:
        """Estimate transcript completeness based on word count."""
        if word_count == 0:
            return 0, "EMPTY"

        percentage = min(100, int((word_count / EXPECTED_WORDS_PER_HOUR) * 100))

        if percentage >= 90:
            status = "COMPLETE"
        elif percentage >= LOW_COMPLETENESS_THRESHOLD:
            status = "PARTIAL"
        else:
            status = "INCOMPLETE"

        return percentage, status

Usage Example

# From citation block file
python3 notion_transcript_extractor.py --block-file blocks.txt

# From MCP fetch JSON output
python3 notion_transcript_extractor.py --json-file notion-output.json

# With custom output directory
python3 notion_transcript_extractor.py --json-file output.json --output-dir ./transcripts

Sample Output

============================================================
EXTRACTION SUMMARY
============================================================

Date         Segments    Words   Complete Status
----------------------------------------------------
2026-01-15        95     6876        95% COMPLETE
2026-01-08        77     4314        59% PARTIAL
2025-11-20        45     2709        37% INCOMPLETE
----------------------------------------------------

⚠️  2 meeting(s) have incomplete transcripts.
   For full content, use Notion's Export feature.

10 Troubleshooting Common Issues

11 Best Practices

Security Best Practices

• Never commit tokens: Add .mcp.json to your .gitignore
• Use environment variables: Set NOTION_TOKEN instead of hardcoding
• Minimal permissions: Only share specific pages your integration needs
• Regular token rotation: Regenerate tokens periodically
• Review integrations: Audit connected integrations in Notion settings quarterly

Rate Limiting & Performance

• Respect limits: Notion allows ~3 requests/second - use 0.35s delays
• Implement backoff: Use exponential backoff on 429 errors
• Batch when possible: Fetch multiple blocks in sequence rather than parallel
• Cache results: Store fetched content locally to avoid repeated API calls
• Monitor usage: Track request counts in production applications

When to Use Citation Extraction vs Notion Export

Alternative Methods for Complete Transcripts

12 Abbreviations & Glossary

? Frequently Asked Questions

Related Reading

Explore more guides and resources on AI, automation, and productivity tools:

• OpenClaw Complete Guide: Free Salesforce-Claude Integration Tool
• Salesforce MCP Server for Claude Code and MCP Clients
• Salesforce Security Ultimate Guide: Protecting Your Org