حد معدل Notion MCP: كيف تربط Notion مع Claude وتصلح الأخطاء

تطلب من Claude ترتيب أربعين ملاحظة اجتماع في Notion، فيتوقف في منتصف الطريق برسالة عن حد المعدل. لا شيء معطّل. Notion يفعل ما تفعله كل خدمة مزدحمة حين تصلها الطلبات أسرع مما تستطيع خدمتها: يقول «انتظر»، والعميل المهذّب ينتظر. المشكلة أن مساعد الذكاء الاصطناعي ليس مهذبًا دائمًا. يمكنه تشغيل بحث، وقراءة النتائج، ثم تشغيل ستة أبحاث أخرى، فيستهلك ميزانية دقيقة كاملة في ثوانٍ معدودة.

يتناول هذا المقال حد معدل Notion MCP من الجانبين. سترى كيف تربط Notion مع Claude، وما الذي تسمح به الحدود فعليًا، وكيف تقرأ الخطأ عند ظهوره، وأي العادات تمنعه من العودة. الأرقام الواردة أدناه مأخوذة من وثائق Notion للمطورين، لذا يمكنك التحقق من كل واحد منها.

💡 الإجابة السريعة: يعمل خادم Notion MCP المستضاف على https://mcp.notion.com/mcp. تنطبق حدود Notion الخاصة بواجهة API على أدواته: 180 طلبًا في الدقيقة على معظم الخطط، و600 على خطتي Business وEnterprise، مع سقف أضيق هو 20 استدعاءً كل 10 ثوانٍ لعمليات البحث واستعلامات مصادر البيانات. عند تجاوز الحد وظهور 429، انتظر المدة المحددة في Retry-After، ثم أرسل طلبات أقل وأكبر حجمًا.

ما معنى حد المعدل في Notion MCP

يشبه حد المعدل صنبورًا لا جدارًا. تمنح Notion كل اتصال كمية ثابتة من الماء في الدقيقة. يمكنك فتح الصنبور على اتساعه وإنفاقها كلها دفعة واحدة، أو تركها تقطر بانتظام. عندما يفرغ الكوب، يُغلق الصنبور حتى تُعاد نافذة الحساب. لا يغيّر بروتوكول سياق النموذج (MCP) هذه القاعدة، بل يغيّر من يمسك الصنبور فقط. مع MCP، من يمسكه هو نموذج ذكاء اصطناعي يقرر بنفسه عدد الاستدعاءات التي يجريها.

الأرقام وراء خطأ 429

فيما يلي الحدود المهمة، مأخوذة من صفحة حدود الطلبات في Notion وصفحة الأدوات المدعومة لديها.

تفصيلتان سهل تفويتهما. أولًا، ميزانية الدقيقة نافذة زمنية، لذا يُسمح بدفعة من 180 استدعاءً في أول عشر ثوانٍ، لكن الاستدعاء رقم 181 ينتظر حتى تُعاد النافذة. ثانيًا، سقفا البحث والاستعلام منفصلان وأضيق بكثير. عشرون استدعاءً في 10 ثوانٍ تعني استدعاءين في الثانية، وهذا أقل من متوسط 3 في الثانية للميزانية العامة. يصل المساعد الذي يبحث في حلقة تكرارية إلى هذا السقف قبل أن يقترب من السقف العام بكثير.

💡 نصيحة: تعدّل Notion حدودها مع الوقت. تعامل مع الجدول كلقطة لحظية، وراجع صفحة حدود الطلبات قبل أن تبني أي شيء يعتمد على رقم دقيق.

لماذا يصل Claude إلى الحد بسرعة

كل استدعاء أداة يجريه Claude هو طلب واحد. أمر مثل "لخّص كل شيء عن إطلاق الربع الثالث" يبدو مهمة واحدة، لكنه يتمدد إلى سلسلة: استدعاء notion-search واحد، ثم عدة استدعاءات notion-fetch للصفحات التي يعيدها، ثم مزيد من الجلب للصفحات الفرعية وقواعد البيانات المرتبطة. الشخص الذي يتنقل في Notion يرسل طلبًا كل بضع ثوانٍ، أما المساعد الذي يعمل وفق خطة فيرسلها متتالية بلا فواصل.

أبرز المسببات:

• عمليات البحث الواسعة التي تعيد صفحات كثيرة، ثم يُجلب كل منها
• حلقات على قواعد البيانات، مثل تعديل 50 صفًا واحدًا تلو الآخر
• إعادة المحاولة الفورية، حيث يكرر النموذج طلبًا فاشلًا دون انتظار
• استدعاءات الأدوات المتوازية، حيث تُرسل عدة طلبات في الثانية نفسها
• المحادثات الطويلة التي تعيد قراءة الصفحات نفسها باستمرار

تمتص Notion الصدمة الأولى. يعيد خادم MCP محاولة الاستدعاء مرة واحدة من تلقاء نفسه عندما يكون الانتظار ثانيتين أو أقل. أي انتظار أطول يعيد خطأً فورًا، وهذا الخطأ هو ما تراه في المحادثة.

ربط Notion مع Claude

يستغرق الربط بضع دقائق ويستخدم OAuth، فلا تلصق أي سر في ملف إعدادات أبدًا. تصف Notion خادم MCP الخاص بها بأنه خادم بعيد مستضاف لدى Notion، ما يعني أنه لا يلزم تثبيت أي شيء في الإعداد القياسي.

إعداد موصل Claude.ai

1. افتح Claude في المتصفح أو في تطبيق سطح المكتب، ثم انتقل إلى الإعدادات (Settings)، ثم الموصلات (Connectors).
2. ابحث عن Notion في دليل الموصلات، ثم اختر Connect.
3. سجّل الدخول إلى Notion عند ظهور نافذة OAuth، ثم اختر مساحة العمل التي تريد أن يصل إليها Claude.
4. وافق على الصلاحيات التي يعرضها Notion في شاشة الموافقة.
5. ابدأ محادثة جديدة، وفعّل موصل Notion، ثم اطلب من Claude العثور على صفحة بالاسم للتأكد من أن الموصل يعمل.

💡 نصيحة: تتغير أسماء القوائم مع تحديثات Anthropic للتطبيق. إذا لم تجد الموصلات (Connectors)، فابحث عن منطقة التكاملات أو الأدوات داخل الإعدادات.

الإضافة في Claude Code

يحتاج Claude Code إلى أمر واحد. توصي وثائق Notion بعنوان Streamable HTTP:

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

نسخ الأمر النصي

ثم شغّل /mcp داخل Claude Code، وأكمل تدفق OAuth في متصفحك. تذكر Notion أنه لا يوجد حتى الآن تفويض غير تفاعلي، لذا لا يستطيع خادم بلا واجهة إتمام تسجيل الدخول وحده. تحدد علامة النطاق من يحصل على الاتصال:

العملاء بلا دعم للخوادم البعيدة

بعض العملاء لا يستطيعون التحدث مع خادم بعيد مباشرة. لهؤلاء، تشير Notion إلى جسر mcp-remote بإعداد STDIO. يوجد عنوان SSE احتياطي على https://mcp.notion.com/sse، لكن عنوان Streamable HTTP هو الموصى به. تسمي Notion أيضًا خادمها القديم مفتوح المصدر مهجورًا ولا تحافظ عليه بنشاط، لذا يجب أن تبدأ الإعدادات الجديدة على الخادم المستضاف. إذا فشل التحقق من الهوية يومًا، فافصل الاتصال ثم أعد وصله، وتأكد من أن حساب Notion لديك له صلاحية على مساحة العمل.

اقرأ الخطأ قبل إصلاحه

تُلام عبارة «حد المعدل» على أكثر مما تستحق. قراءة الاستجابة الفعلية توفر ساعة من التخمين.

رصد rate_limited و Retry-After

عند تجاوز الحد، ترد API الخاصة بـ Notion بحالة HTTP رقمها 429 ورمز الخطأ rate_limited. تحمل الاستجابة ترويسة Retry-After بعدد صحيح من الثواني، وتكرر هذه القيمة في additional_data.retry_after للعملاء الذين لا يستطيعون قراءة الترويسات.

عبر MCP تصل الفكرة نفسها بشكل أكثر ودّية. إذا كان الانتظار ثانيتين أو أقل، يعيد الخادم المحاولة مرة واحدة بنفسه. وإذا كان أطول، يفشل استدعاء الأداة فورًا ويعيد الحقلين retry_after_seconds و rate_limit_reason. يرى Claude هذين الحقلين، ويخبره الأمر النصي الجيد بالضبط بما يفعله بهما.

قيود البحث والاستعلام

هنا يتعثر معظم المساعدين. يسمح كل من notion-search وnotion-query-data-sources بحد 20 استدعاءً كل 10 ثوانٍ. نموذج يبحث عن الصفحة الصحيحة عبر عمليات بحث متكررة يستنزف هذا الحد في لحظات، حتى لو كانت ميزانية الدقيقة العامة شبه سليمة. حقل rate_limit_reason هو أول مكان تنظر فيه حين تحتاج إلى معرفة أي حد رفض الاستدعاء.

هل هو فعلًا حد معدل؟

عدة مشكلات تبدو كأنها تقييد وليست كذلك. طابق العَرَض قبل أن تغيّر أي شيء.

تحدد صفحة حدود Notion سقفًا لحمولة واحدة هو 1,000 عنصر كتلة و500 KB، مع حصر مصفوفات أنواع الكتل (بما في ذلك النص المنسق) بحد 100 عنصر. يُحدّ محتوى النص في الخاصية بحد 2,000 حرف. قد يفشل لصق كبير لهذه الأسباب، ويبدو في البداية كأنه تقييد.

إصلاح أخطاء حد المعدل بسرعة

أرسل طلبات أقل وأكبر حجمًا

أرخص طلب هو الذي لا ترسله أبدًا. بدلًا من أن تطلب من Claude تعديل أربعين صفًا واحدًا تلو الآخر، اطلب منه بناء التغيير الكامل لصفحة وتطبيقه في استدعاء notion-update-page واحد، مع البقاء ضمن حدود الحمولة البالغة 1,000 كتلة و500 KB. استدعاء واحد ينجز عشرة أشياء يُحسب طلبًا واحدًا من الميزانية.

تحركات عملية:

• جمّع التعديلات حسب الصفحة، بحيث تُلمس كل صفحة مرة واحدة
• قسّم المهام الكبيرة إلى دفعات من 20 إلى 30 عنصرًا في كل رسالة محادثة
• أنشئ المحتوى في مرور واحد باستخدام notion-create-pages بدلًا من إضافة الكتل قطعة قطعة

لجم حلقة البحث

البحث هو أغلى عادة، لأن كل بحث يتبعه جلب. أعطِ Claude العناوين المباشرة كلما توفرت لديك. عنوان الصفحة أو معرفها يتيح له استدعاء notion-fetch فورًا، دون أي بحث. في عمل قواعد البيانات، يعيد استدعاء notion-query-data-sources مُرشّحًا الصفوف التي تحتاجها دفعة واحدة، بينما ستعيد عمليات البحث المتكررة شظايا وتستهلك سقف 20 استدعاءً كل 10 ثوانٍ. عندما تحتاج فعلًا إلى البحث، اطلب استعلامًا واحدًا محدد النطاق. يدعم notion-search مرشحات للموقع والمنشئ والتاريخ والحالة، والاستعلام الضيق يعيد صفحات أقل للجلب لاحقًا.

أوامر نصية توقف عواصف إعادة المحاولة

أفضل حل لا يكلّف شيئًا: أخبر Claude كيف يتصرف عندما ترفض Notion. الصق كتلة مثل هذه في بداية مهمة كبيرة:

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.

نسخ الأمر النصي

السطر الأخير شبكة أمان. إذا توقفت المحادثة عند الصفحة 22، تعرف بالضبط أين تستأنف، ولا تدفع ثمن الصفحات نفسها مرتين.

اعرف متى تترقّى

تحصل اتصالات Business و Enterprise على 600 طلب في الدقيقة، أي 3.3 مرات قدر حد 180 في الخطط الأخرى. هذا يفيد في الأتمتة الثقيلة. تذكر Notion سقفي البحث والاستعلام منفصلين، بوصفهما 20 استدعاءً كل 10 ثوانٍ، لذا لا ترفعهما ميزانية الخطة الأكبر بوضوح. أصلح العادات أولًا، ثم ادفع ثمن مساحة إضافية إذا لم تتناسب الأرقام بعد ذلك. استدعِ notion-get-tool-access لترى الأدوات التي تتيحها خطة مساحة عملك.

خمسة أخطاء تستنزف ميزانيتك

1. طلب "كل شيء" في أمر نصي واحد، وهذا يتمدد إلى مئات عمليات الجلب
2. ترك Claude يعيد المحاولة فورًا بدلًا من انتظار المدة المذكورة
3. البحث عن صفحات لديك عنوانها بالفعل
4. تشغيل عدة مهام ثقيلة معًا، فتتنافس على الميزانية نفسها
5. تجاهل نص الخطأ، ثم إرسال الأمر النصي نفسه مرة أخرى

كتابة منطق إعادة المحاولة للنصوص البرمجية

إذا كنت تستدعي Notion من نصوصك البرمجية الخاصة إلى جانب Claude، فالإيقاع أفضل من الاندفاع. نصيحة Notion نفسها أن تُبقي منطق إعادة المحاولة في مكان مركزي واحد، وأن تحترم Retry-After، وأن تستخدم التراجع الأُسّي (exponential backoff) مع الاضطراب العشوائي (jitter)، وأن تحدّ التأخيرات الاحتياطية عند 30 ثانية، وأن تقيّد إجمالي عدد المحاولات.

التراجع مع الاضطراب العشوائي

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")

نسخ الأمر النصي

الاضطراب العشوائي مهم. بدونه، يعيد عشرة عمال فشلوا معًا المحاولة معًا، ويفشلون معًا مرة أخرى. نصف ثانية عشوائية تفرّقهم.

تحذير من وثائق Notion: إذا أعاد استدعاء كتابة الرمز 503، فتحقق من additional_data.retry_guidance قبل تكراره، لأن التغيير ربما يكون محفوظًا بالفعل. إعادة المحاولة العمياء للكتابة قد تنشئ نسخًا مكررة.

تنظيم الطلبات قبل أن تفشل

يتفاعل التراجع مع الفشل بعد وقوعه، أما التنظيم فيتجنبه. وزّع الطلبات بالتساوي، وابقَ قرب 80 بالمئة من الميزانية:

تسمح Notion بالاندفاعات، لذا يكون التنظيم اختياريًا للمهام القصيرة. أما للتشغيلات الطويلة غير المراقبة فهو الفرق بين إنهاء سلس وجدار من الأخطاء. امنح استدعاءات البحث والاستعلام إيقاعًا أبطأ خاصًا بها: استدعاء كل 0.6 ثانية تقريبًا يبقيك دون 20 كل 10 ثوانٍ.

استخدم Claude Sonnet 5 على PicassoIA

حين تكون المشكلة في الكود، يوفر نموذج البرمجة الوقت. يقرأ Claude Sonnet 5 على PicassoIA الخطأ، ويكتب الإصلاح، ويقبل لقطات الشاشة كمدخلات. ولتكن واضحًا، فهو يصوغ النصوص البرمجية والأوامر النصية لك، لكنه لا يتصل بمساحة عمل Notion الخاصة بك بنفسه.

1. افتح صفحة Claude Sonnet 5 على PicassoIA.
2. الصق الخطأ الخام في الأمر النصي (Prompt): استجابة 429، وقيمة retry_after_seconds، وجملة واحدة عما كنت تفعله.
3. اختر مستوى الجهد (Effort). الافتراضي، أي المنخفض، يجيب بأسرع وقت. اختر المتوسط أو المرتفع لمنطق إعادة المحاولة الذي يمس عدة ملفات.
4. اترك الحد الأقصى للتوكنات (Max Tokens) عند 8,192 لغلاف إعادة محاولة كامل مع شرح، أو خفّضه للإجابات السريعة.
5. أضف موجّه النظام (System Prompt) مثل "أنت مهندس خلفيات حريص. أجب بالكود أولًا، ثم بشرح من ثلاثة أسطر."
6. أرفق لقطة شاشة للخطأ في حقل الصورة (Image) إذا كان النص صعب النسخ.
7. شغّله، واقرأ النتيجة، واختبر الكود على دفعة صغيرة قبل التشغيل الكبير.

للمهام البرمجية متعددة الخطوات والأصعب، يوجد Claude Fable 5 في مجموعة النماذج اللغوية الكبيرة (Large Language Models) نفسها.

أنشئ صورك الخاصة على Picasso IA

حين تعمل مساحة Notion بسلاسة، امنحها صورًا أفضل. تحوّل صورة الرأس القوية صفحة مشروع أو الصفحة الرئيسية لويكي أو موجز إطلاق من جدار من النص إلى شيء يرغب الناس في فتحه. يحوّل PicassoIA Image و Seedream 5 Pro أمرًا نصيًا من سطر واحد إلى صورة واقعية كالصور الفوتوغرافية، وكل نتيجة جاهزة للإسقاط في صفحة Notion.

جرّب أمرًا نصيًا بهذا الشكل: الشخص، المكان، الإضاءة، العدسة. مثلًا: «مدير مشروع يراجع خرائط طريق مطبوعة على طاولة مشمسة، إضاءة نافذة ناعمة، عدسة 50 ملم، حبيبات فيلم طبيعية». غيّر تفصيلًا واحدًا في كل مرة، وستعرف ما تفعله كل كلمة.

افتح Picasso IA، واختر نموذجًا، وأنشئ أول صورة رأس لك اليوم. تصفح كل النماذج المتاحة على picassoia.com/en/all-models، وواصل التجربة حتى تبدو صفحات Notion بجمال عملها.