/ الدليل / الملعب / FastMCP
← كل الخوادم ↗ GitHub
● رسمي PrefectHQ ⚡ فوري

FastMCP

بواسطة PrefectHQ · PrefectHQ/fastmcp

الطريقة البيثونية لبناء خوادم MCP — زيّن دالة واحصل على أداة. شحن MCP في 20 سطر.

FastMCP هو إطار عمل Python لبناء خوادم MCP (وليس خادماً للتثبيت). ديكوريتور واحد @mcp.tool يحول دالة مكتوبة النوع إلى أداة MCP، مع اشتقاق المخطط تلقائياً من تعليقاتك. يتولى نقل stdio/SSE ودورة الحياة وتفاصيل البروتوكول، ليتركك تركز على منطق العمل فقط.

▶ شاهد العرض 📦 التثبيت 💡 حالات الاستخدام

لماذا تستخدمه

الميزات الأساسية

عرض مباشر

كيف يبدو في الممارسة

fastmcp.replay ▶ جاهز
0/0

التثبيت

اختر العميل

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

افتح Claude Desktop → Settings → Developer → Edit Config. أعد التشغيل بعد الحفظ.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

يستخدم Cursor نفس مخطط mcpServers مثل Claude Desktop. إعدادات المشروع أولى من الإعدادات العامة.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

انقر على أيقونة MCP Servers في شريط Cline الجانبي، ثم "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

نفس الصيغة مثل Claude Desktop. أعد تشغيل Windsurf لتطبيق التغييرات.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "fastmcp",
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  ]
}

يستخدم Continue مصفوفة من كائنات الخادم بدلاً من خريطة.

~/.config/zed/settings.json
{
  "context_servers": {
    "fastmcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastmcp"
        ]
      }
    }
  }
}

أضف إلى context_servers. يعيد Zed التحميل تلقائيًا عند الحفظ.

claude mcp add fastmcp -- uvx fastmcp

أمر من سطر واحد. تحقق باستخدام claude mcp list. احذف باستخدام claude mcp remove.

حالات الاستخدام

استخدامات عملية: FastMCP

عرض REST API داخلي كـ MCP في أقل من ساعة

👤 مهندسو الواجهة الخلفية الذين لديهم خدمة Python موجودة ⏱ ~45 min intermediate

متى تستخدمه: لديك API للشركة يجب أن يتمكن الوكلاء من استدعاؤه، ولا تريد كتابة مواصفات العميل من الصفر.

المتطلبات الأساسية
  • Python 3.10+ — python --version
  • تثبيت uv — curl -LsSf https://astral.sh/uv/install.sh | sh
الخطوات
  1. إنشاء المشروع
    قم بإنشاء مشروع خادم FastMCP يسمى 'acme-api-mcp' بأداة بدء واحدة. استخدم uv لإدارة الاعتماديات.✓ تم النسخ
    → pyproject.toml + server.py مع مثال @mcp.tool يعمل
  2. تغليف أهم ثلاث نقاط نهاية
    يحتوي API الداخلي على نقاط النهاية /orders/{id}، /customers/search، /invoices/{id}/pdf. اكتب أداة FastMCP لكل منها، باستخدام httpx.AsyncClient وقراءة AUTH_TOKEN من env.✓ تم النسخ
    → 3 دوال مزينة مع تلميحات النوع + docstrings التي تصبح وصفات الأداة
  3. اختبر محليًا مع مفتش MCP
    قم بتشغيل الخادم باستخدام uv run mcp dev server.py. افتح المفتش واستدعِ كل أداة بإدخال واقعي.✓ تم النسخ
    → تُرجع الأدوات JSON متوقعاً، لا توجد تتبعات مكدس

النتيجة: خادم MCP يعمل يمكنك توجيهه إلى Claude Desktop أو أي عميل MCP.

المزالق
  • تسرب الأسرار في وصفات الأداة لأنك طبعتها في docstrings — استخدم docstrings لوصف السلوك وليس الأمثلة برموز حقيقية. حمّل الأسرار من os.environ ولا تطبعها أبداً في الأخطاء
  • خلط المتزامن مع غير المتزامن، يسبب أخطاء حلقة الحدث — اختر أحدهما — إذا كان عميل HTTP غير متزامن، اجعل الأداة كاملة غير متزامنة؛ لا تستدعِ asyncio.run داخل أداة

عرض مستندات الشركة كموارد MCP للـ RAG

👤 مهندسو المنصة الذين يبنون بنية تحتية للوكلاء ⏱ ~30 min intermediate

متى تستخدمه: تريد من الوكيل اكتشاف معرفة الشركة تلقائياً وسحبها بدون استدعاءات أداة لكل ملف.

الخطوات
  1. تحديد قائمة المورد
    حدد مورد FastMCP في URI docs://{path} يسرد جميع ملفات markdown في ./docs/ ويُرجع محتواها عند القراءة.✓ تم النسخ
    → تم تسجيل المورد، يُظهر المفتش القائمة
  2. إضافة مورد قالب
    أضف قالب مورد docs://{category}/{slug} يُرجع الملف المطابق. وثّق قيم {category} الصحيحة.✓ تم النسخ
    → تم تسجيل القالب، تعمل الجلبات المعاملة
  3. اختبر في عميل حقيقي
    اربط Claude Desktop بالخادم. تحقق من أن قائمة الموارد تسرد المستندات وتُحمّل المحتوى.✓ تم النسخ
    → تظهر الموارد كسياق قابل للإرفاق

النتيجة: سطح معرفة مدعوم بمورد يمكن للوكيل سحبه بشكل أصلي — أنظف من استدعاءات الأداة للمحتوى الثابت.

المزالق
  • قوائم الموارد الكبيرة تغمر واجهة العميل — قم بالترقيم أو التصفية في نقطة النهاية؛ لا يحتاج كل ملف إلى الظهور

نشر خادم FastMCP كنقطة نهاية SSE بعيدة

👤 مهندسو المنصة الذين يخدمون فرقاً متعددة ⏱ ~60 min advanced

متى تستخدمه: عدة مطورين بحاجة لـ MCP واحد — استضفه مرة، لا تجعل الجميع يشغّل stdio محليًا.

المتطلبات الأساسية
  • مضيف الحاوية (Cloud Run، Fly، Railway) — أي وقت تشغيل يدعم Docker
الخطوات
  1. تبديل النقل إلى SSE
    عدّل server.py لتشغيل mcp.run(transport='sse', host='0.0.0.0', port=8080). أضف Dockerfile بسيط.✓ تم النسخ
    → curl localhost:8080/sse محليًا يُظهر مصافحة SSE
  2. نشر خلف المصادقة
    انشر إلى Cloud Run مع مصادقة IAM. واجهة /sse بفحص مصادقة قائم على الرؤوس في وسيط FastAPI.✓ تم النسخ
    → URL عام مع 401 للطلبات غير المصرح لها
  3. وصّل العملاء
    شارك أمر الاتصال مع الفريق: npx -y mcp-remote https://mcp.acme.com/sse. تحقق من عملاء Claude Desktop الخاصة بهم تلتقط الأدوات.✓ تم النسخ
    → يرى أعضاء الفريق الأدوات نفسها في عملائهم

النتيجة: MCP بعيد مشترك — قاعدة رمز واحدة، مستخدمون متعددون، سهل التحديث.

المزالق
  • اتصالات SSE تنقطع خلف بعض جدران الحماية الشركاتية — استخدم نقل HTTP قابل للبث بدلاً من ذلك (مواصفات أحدث) أو وثّق متطلب VPN/المسار المباشر
اجمعها مع: cloud-run

التركيبات

اجمعها مع خوادم MCP أخرى لتحقيق نتائج x10

fastmcp + cloud-run

بناء مرة واحدة، نشر إلى Cloud Run، شارك مع الفريق

غلّف API التسعير الداخلي الخاص بي كخادم FastMCP، وحاويه، وانشره إلى Cloud Run مع مصادقة IAM.✓ تم النسخ
fastmcp + fastapi-mcp

مقارنة الأساليب — FastMCP للمشاريع الجديدة، fastapi-mcp لتطبيقات FastAPI الموجودة

لديّ خدمة FastAPI موجودة. هل أضيف fastapi-mcp لعرضها أم أعيد الكتابة في FastMCP؟ قارن بناءً على مساراتي.✓ تم النسخ

الأدوات

ما يوفره هذا الـ MCP

الأداةالمدخلاتمتى تستدعيهاالتكلفة
@mcp.tool decorated function with typed signature غلّف أي دالة تريد للوكلاء استدعاؤها free
@mcp.resource URI template + function عرّض محتوى قابل للقراءة (مستندات، إعدادات، لقطات البيانات) free
@mcp.prompt decorated function returning Message[] وفّر قوالب prompt قابلة لإعادة الاستخدام متعددة الأدوار للعملاء free
mcp.run transport: 'stdio'|'sse'|'streamable-http', host?, port? نقطة دخول — استدعِ في نهاية السكريبت الرئيسي free
Context (ctx) parameter inject ctx: Context into any tool الأدوات طويلة الأمد التي تحتاج لنقل التقدم أو السجل free

التكلفة والحدود

تكلفة التشغيل

حصة API
لا شيء — هذا إطار عمل وليس خدمة
الرموز لكل استدعاء
خادمك يشغّل أي استدعاءات LLM؛ كبداية الإطار عمل لا تذكر
التكلفة المالية
مجاني، مفتوح المصدر
نصيحة
استخدم الموارد بدلاً من الأدوات للمحتوى الثابت — الموارد أرخص في tokens لأنها معلنة مسبقًا

الأمان

الصلاحيات والأسرار ونطاق الأثر

تخزين بيانات الاعتماد: اختيارك — متغيرات البيئة بديهية؛ حمّل الأسرار عند بدء العملية وليس في كل استدعاء
نقل البيانات الخارجي: أينما تصل دوال الأداة الخاصة بك

استكشاف الأخطاء

الأخطاء الشائعة وحلولها

Tool schema missing required fields in the client

معاملات الدالة تحتاج تلميحات نوع. def foo(x) ينتج مخطط عديم الفائدة — استخدم def foo(x: str) مع docstring.

تحقق: شغّل `uv run mcp dev server.py` وتحقق من مخطط أداة المفتش
Server starts but client sees 0 tools

أنت تخلط stdio مع إعدادات SSE خاطئة. للـ Claude Desktop استخدم transport='stdio'؛ للـ mcp-remote استخدم 'sse'.

`ImportError: No module named 'fastmcp'`

ثبّت مع uv pip install fastmcp أو أضف لتبعيات pyproject.toml. تحقق من تشغيل الخادم من نفس venv.

تحقق: uv pip show fastmcp
Async tool hangs on first call

استوردت httpx المتزامن داخل أداة غير متزامنة. استخدم httpx.AsyncClient مع async with — لا تخلط أبداً.

البدائل

FastMCP مقابل البدائل

البديلمتى تستخدمهاالمقايضة
TypeScript MCP SDKأنت متجر TS/Node وتريد البقاء هناكرسمي، موثوق، DX مماثل — لغة مختلفة فقط
fastapi-mcpلديك تطبيق FastAPI موجود وتريد عرض المسارات كأدواتتحكم أقل على سطح MCP لكن بدون إعادة تصميم لخدمات موجودة
csharp-sdkمتجر .NETمن الطرف الأول، لكن نظام بيئي أصغر من الأمثلة

المزيد

الموارد

📖 اقرأ ملف README الرسمي على GitHub

🐙 تصفح القضايا المفتوحة

🔍 تصفح أكثر من 400 خادم MCP و Skills