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__retrieve-a-block",
      "mcp__notion-local__get-block-children"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": [
    "notion-local"
  ]
}

The permission names above use the local server's v2.x tool naming (version 2.1.0 as of January 2026), which uses bare names alongside renamed tools such as query-data-source, retrieve-a-data-source, move-page, and retrieve-page-markdown. If you are still on a v1.x release, each tool name carries an API- prefix instead, so update older allowlists when upgrading.

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_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

These five core tools are the ones you will reach for most, but as of mid-2026 the hosted server exposes 23 tools in total, per the supported tools reference. Notable additions include notion-query-meeting-notes (covered in Section 8), notion-move-pages, notion-duplicate-page, notion-create-database, notion-create-view, notion-query-data-sources, and file-upload tools.

Self-Hosted MCP Tools (notion-local)

6 AI Meeting Notes: How It Worked Before March 2026

Notion's AI Meeting Notes feature automatically generates transcripts from recorded meetings. For years, accessing these transcripts programmatically via the Notion API was blocked - a significant limitation for automation workflows. API version 2026-03-11 changed that (see Section 8); this section documents how the API behaved before that release, which still applies to integrations pinned to older API versions.

The Core Issue (Pre-2026-03-11)

On API versions before 2026-03-11, fetching a page containing AI Meeting Notes returned a placeholder in place of the transcript sections:

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

This wasn't a bug or configuration issue - it was a deliberate limitation in Notion's API design at the time. The transcription block type was explicitly unsupported until the 2026-03-11 release renamed it to meeting_notes and made it a supported block type.

What You Saw vs What You Got

Why This Mattered

• Automation Blocked: Could not automatically export meeting transcripts for CRM, project management, or documentation systems
• Search Limitations: AI Meeting Notes appeared in search results but full content could not be retrieved
• Workflow Integration: Zapier, n8n, and other automation tools faced the same limitation
• Archive Challenges: No programmatic way existed to back up or migrate meeting transcripts

7 Five Approaches That Failed Before 2026-03-11

Before the 2026-03-11 API version introduced meeting_notes support - and before discovering the citation extraction workaround - I tested multiple approaches to access meeting transcripts via the Notion API. Understanding why each approach failed on older API versions helps explain the architecture of both the workaround and the eventual official solution.

8 Meeting Notes via API: The 2026-03-11 Update

According to the Notion API changelog and the versioning reference, API version 2026-03-11 is the first release that treats AI Meeting Notes as a first-class API citizen. Everything in Sections 6 and 7 describes how earlier versions behaved; once you send the Notion-Version: 2026-03-11 header, the picture changes substantially.

The meeting_notes Block Type

The block type that previously surfaced as unsupported is now returned as a supported meeting_notes block with three child block IDs:

In practical terms, the transcript block is now addressable via transcript_block_id - the very ID that pre-2026-03-11 versions refused to resolve. How much transcript text you can retrieve end-to-end depends on your workspace configuration, plan, and integration capabilities, so test full retrieval in your own workspace before building a production pipeline around it.

# Retrieve a meeting_notes block on the 2026-03-11 API version
curl "https://api.notion.com/v1/blocks/$MEETING_NOTES_BLOCK_ID" 
  -H "Authorization: Bearer $NOTION_TOKEN" 
  -H "Notion-Version: 2026-03-11"

# The response exposes child references such as transcript_block_id -
# fetch that block next to work with the transcript

Two New Endpoints

• Create a meeting note: Generates AI meeting notes from uploaded audio or video files. Transcription and summary generation run asynchronously after the request is accepted.
• Query meeting notes (added May 11, 2026): Retrieves meeting-note blocks with their metadata and child block IDs. It requires the read-content capability, a workspace with AI Meeting Notes enabled, and the integration user to be an attendee of the meeting.

Hosted MCP: notion-query-meeting-notes

The hosted MCP server (mcp.notion.com) now includes a notion-query-meeting-notes tool as part of its 23-tool lineup, per the supported tools reference. That means Claude can look up meeting-note blocks conversationally - no custom scripting required - as long as the workspace and attendee requirements above are met.

9 The Citation Extraction Workaround

Back on pre-2026-03-11 API versions, after five failed approaches I discovered a workaround that provides partial transcript access - and it remains a dependable fallback today for integrations pinned to older API versions or legacy tokens. 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:

10 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
# 2026-03-11 is the latest API version and is required for the meeting-notes
# endpoints; 2022-06-28 still works for basic block reads, but the JS SDK v5+
# no longer supports it, so standardize on the current version.
NOTION_API_VERSION = "2026-03-11"
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.

11 Troubleshooting Common Issues

12 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 per integration, plus plan-scaled workspace-level limits - 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

13 Abbreviations & Glossary

? Frequently Asked Questions

Related Reading

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

• ClawdBot Complete Guide: Open Source AI Assistant (2026)
• Salesforce MCP Server for Claude Code and MCP Clients: Setup Guide
• Salesforce Security Ultimate Guide: Protecting Your Org