Notion MCP Rate Limit: Connect Notion to Claude and Fix Errors

You ask Claude to tidy forty meeting notes in Notion, and halfway through it stops with a message about a rate limit. Nothing is broken. Notion is doing what every busy service does when requests arrive faster than it wants to serve them: it says "wait," and a polite client waits. The trouble is that an AI assistant is not always polite. It can run a search, read the results, run six more searches, and spend a whole minute of budget in a few seconds.

This article walks through the Notion MCP rate limit from both sides. You will see how to connect Notion to Claude, what the limits actually allow, how to read the error when it appears, and which habits keep it from coming back. The numbers below come from Notion's own developer documentation, so you can check every one of them.

💡 Quick answer: Notion's hosted MCP server lives at https://mcp.notion.com/mcp. Notion's API limits apply to its tools: 180 requests per minute on most plans, 600 on Business and Enterprise, plus a tighter cap of 20 calls per 10 seconds on search and data source queries. When you hit a 429, wait the Retry-After time, then send fewer and bigger requests.

What the Notion MCP Rate Limit Means

A rate limit works like a faucet, not a wall. Notion hands each connection a fixed amount of water per minute. You can open the valve wide and spend it all at once, or let it drip evenly. When the cup is empty, the tap closes until the window resets. The Model Context Protocol (MCP) does not change that rule. It only changes who is holding the tap. With MCP, the one holding it is an AI model that decides on its own how many calls to make.

The Numbers Behind the 429

Here are the limits that matter, taken from Notion's request limits page and its supported tools page.

Two details are easy to miss. First, the per-minute budget is a window, so a burst of 180 calls in the first ten seconds is allowed, but call 181 waits until the window resets. Second, the search and query caps are separate and much tighter. Twenty calls in 10 seconds is two per second, which is below the 3 per second average of the general budget. An assistant that searches in a loop reaches that ceiling long before it touches the general one.

💡 Tip: Notion adjusts its limits over time. Treat the table as a snapshot and check the request limits page before you build anything that depends on an exact number.

Why Claude Hits the Limit Fast

Every tool call Claude makes is one request. A prompt like "summarize everything about the Q3 launch" feels like a single task, but it expands into a chain: one notion-search, several notion-fetch calls for the pages it returns, then more fetches for child pages and linked databases. A person clicking through Notion makes a request every few seconds. An assistant working through a plan makes them back to back.

Common triggers:

• Broad searches that return many pages, each of which then gets fetched
• Loops over databases, such as editing 50 rows one at a time
• Instant retries, where the model repeats a failed request without waiting
• Parallel tool calls, where several requests leave in the same second
• Long chats that keep re-reading the same pages

Notion softens the first hit. The MCP server retries a call once on its own when the wait is two seconds or less. Anything longer returns an error straight away, and that error is the one you see in the chat.

Connect Notion to Claude

Connecting takes a few minutes and uses OAuth, so you never paste a secret into a config file. Notion describes its MCP server as a remote server hosted by Notion, which means there is nothing to install for the standard setup.

Set Up the Claude.ai Connector

1. Open Claude in your browser or desktop app and go to Settings, then Connectors.
2. Find Notion in the connector directory and choose Connect.
3. Sign in to Notion when the OAuth window opens and pick the workspace you want Claude to reach.
4. Approve the access that Notion lists on the consent screen.
5. Start a new chat, switch the Notion connector on, and ask Claude to find a page by name to confirm that it works.

💡 Tip: Menu names move as Anthropic updates the app. If you cannot find Connectors, look for an integrations or tools area inside Settings.

Add It in Claude Code

Claude Code needs one command. Notion's documentation recommends the Streamable HTTP address:

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

Copy Prompt

Next, run /mcp inside Claude Code and finish the OAuth flow in your browser. Notion states that no non-interactive authorization exists yet, so a headless server cannot finish the sign-in on its own. The scope flag decides who gets the connection:

Clients Without Remote Support

Some clients cannot talk to a remote server directly. For those, Notion points to the mcp-remote bridge with a STDIO configuration. A fallback SSE address exists at https://mcp.notion.com/sse, but the Streamable HTTP address is the recommended one. Notion also calls its older open-source server deprecated and does not actively maintain it, so new setups belong on the hosted server. If a connection ever fails to authenticate, disconnect it, reconnect, and check that your Notion account has permission on the workspace.

Read the Error Before You Fix It

The words "rate limit" get blamed for more than they deserve. Reading the actual response saves an hour of guessing.

Spot rate_limited and Retry-After

When you pass the limit, Notion's API answers with HTTP status 429 and the error code rate_limited. The response carries a Retry-After header with a whole number of seconds, and it repeats that value in additional_data.retry_after for clients that cannot read headers.

Through MCP the same idea arrives in a friendlier shape. If the wait is two seconds or less, the server retries once by itself. If it is longer, the tool call fails right away and returns retry_after_seconds and rate_limit_reason. Claude sees those fields, and a good prompt tells it exactly what to do with them.

Search and Query Throttles

The tool-specific caps are where most assistants trip. notion-search and notion-query-data-sources each allow 20 calls per 10 seconds. A model hunting for the right page through repeated searches burns that in moments, even when the general minute budget is nearly untouched. The rate_limit_reason field is the first place to look when you need to know which limit refused the call.

Is It Really a Rate Limit?

Several problems look like throttling and are not. Match the symptom before you change anything.

Notion's limits page caps a single payload at 1,000 block elements and 500 KB, with arrays of block types (including rich text) limited to 100 elements. Text content in a property tops out at 2,000 characters. A large paste can fail for those reasons and look like a throttle at first glance.

Fix Rate Limit Errors Fast

Send Fewer, Bigger Requests

The cheapest request is the one you never send. Instead of asking Claude to edit forty rows one at a time, ask it to build the full change for a page and apply it in a single notion-update-page call, staying under the 1,000 block and 500 KB payload limits. One call that does ten things counts as one request against the budget.

Practical moves:

• Group edits by page, so each page is touched once
• Chunk big jobs into batches of 20 to 30 items per chat message
• Create content in one pass with notion-create-pages rather than adding blocks piece by piece

Tame the Search Loop

Searching is the most expensive habit because every search is followed by fetches. Give Claude direct addresses whenever you have them. A page URL or ID lets it call notion-fetch straight away, with no search at all. For database work, a filtered notion-query-data-sources call returns the rows you need in one shot, where repeated searches would return fragments and burn the 20 calls per 10 seconds cap. When you do need to search, ask for one well-scoped query. notion-search supports filters for location, creator, date and status, and a narrow query returns fewer pages to fetch afterward.

Prompts That Stop Retry Storms

The best fix costs nothing: tell Claude how to behave when Notion says no. Paste a block like this at the start of a big task:

Update the 30 pages in the "Meeting Notes" database one at a time.
Use notion-fetch with the page URL instead of searching for each page.
Run one Notion call at a time. If a call returns a rate limit error,
wait the number of seconds in retry_after_seconds, then continue from the same page.
After every 10 pages, tell me which pages are finished and which are left.

Copy Prompt

The last line is a safety net. If the chat dies at page 22, you know exactly where to resume, and you do not pay for the same pages twice.

Know When to Upgrade

Business and Enterprise connections get 600 requests per minute, 3.3 times the 180 on other plans. That helps with heavy automation. Notion lists the search and query caps separately, as 20 calls per 10 seconds, so a bigger plan budget does not obviously lift them. Fix the habits first, then pay for headroom if the numbers still do not fit. Call notion-get-tool-access to see which tools your workspace plan makes available.

Five Mistakes That Burn Your Budget

1. Asking for "everything" in one prompt, which expands into hundreds of fetches
2. Letting Claude retry instantly instead of waiting the stated time
3. Searching for pages you already have the URL for
4. Running several heavy tasks at once, so they compete for the same budget
5. Ignoring the error text, then sending the same prompt again

Write Retry Logic for Scripts

If you call Notion from your own scripts next to Claude, rhythm beats rush. Notion's own advice is to keep retry logic in one central place, respect Retry-After, use exponential backoff with jitter, cap fallback delays at 30 seconds, and limit the total number of attempts.

Backoff With Jitter

import random
import time

import requests


def notion_request(method, url, headers, max_attempts=5, **kwargs):
    for attempt in range(max_attempts):
        response = requests.request(method, url, headers=headers, **kwargs)
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after:
            wait = int(retry_after)
        else:
            wait = min(2 ** attempt, 30)

        time.sleep(wait + random.uniform(0, 0.5))

    raise RuntimeError("Still rate limited after all attempts")

Copy Prompt

The jitter matters. Without it, ten workers that failed together all retry together and fail together again. A random half second spreads them out.

One warning from Notion's docs: if a write returns a 503, check additional_data.retry_guidance before repeating it, because the change may already be saved. Blind retries on writes can create duplicates.

Pace Requests Before They Fail

Backoff reacts to failure. Pacing avoids it. Spread requests evenly and stay near 80 percent of the budget:

Notion allows bursts, so pacing is optional for short jobs. For long unattended runs it is the difference between a smooth finish and a wall of errors. Give search and query calls their own slower pace: one call every 0.6 seconds or so keeps you under 20 per 10 seconds.

Use Claude Sonnet 5 on PicassoIA

When the problem is code, a coding model saves time. Claude Sonnet 5 on PicassoIA reads an error, writes a fix, and accepts screenshots as input. To be clear, it drafts scripts and prompts for you. It does not connect to your Notion workspace itself.

1. Open the Claude Sonnet 5 page on PicassoIA.
2. Paste the raw error into Prompt: the 429 response, the retry_after_seconds value, and one sentence about what you were doing.
3. Choose an Effort level. The default, low, answers fastest. Pick medium or high for retry logic that touches several files.
4. Leave Max Tokens at 8,192 for a full retry wrapper plus an explanation, or lower it for quick answers.
5. Add a System Prompt such as "You are a careful backend engineer. Reply with code first, then a three line explanation."
6. Attach a screenshot of the error in the Image field if the text is hard to copy.
7. Run it, read the result, and test the code against a small batch before a big run.

For harder multi-step coding jobs, Claude Fable 5 sits in the same Large Language Models collection.

Make Your Own Images on Picasso IA

Once your Notion workspace runs smoothly, give it better visuals. A strong header image turns a project page, a wiki home or a launch brief from a wall of text into something people want to open. PicassoIA Image and Seedream 5 Pro turn a one line prompt into a photorealistic picture, and every result is ready to drop into a Notion page.

Try a prompt in this shape: subject, setting, light, lens. For example, "a project manager reviewing printed roadmaps at a sunlit table, soft window light, 50mm lens, natural film grain." Change one detail at a time and you will see what each word does.

Open Picasso IA, pick a model, and make your first header image today. Browse every available model at picassoia.com/en/all-models, and keep experimenting until your Notion pages look as good as they work.