كيفية بناء خادم MCP: دليل خطوة بخطوة بلغتي Python وTypeScript (2026)

يمكنك بناء خادم MCP يستدعيه Claude فعليًا في نحو 15 دقيقة. قِسنا ذلك على Node 20 وPython 3.11: أداة add فعّالة، تعمل عبر stdio ويلتقطها Claude Desktop، استغرقت 14 دقيقة في المرة الأولى وأقل من 5 بمجرد معرفة البنية. يبني هذا الدليل الخادم نفسه مرتين، مرة بلغة Python مع FastMCP 2.x ومرة بلغة TypeScript مع @modelcontextprotocol/sdk 1.x، حتى تختار مجموعتك التقنية وتنسخ كودًا حقيقيًا. إذا أردت المعمارية ونظرية البروتوكول أولًا، فإن دليلنا حول Model Context Protocol يغطي ذلك؛ هنا نبني فقط.

بداية سريعة لخادم MCP: ما الذي ستبنيه

خادم MCP برنامج صغير يكشف أدوات وبيانات وقوالب مطالبات لعملاء الذكاء الاصطناعي مثل Claude وCursor وVS Code عبر Model Context Protocol. تكتب الخادم مرة واحدة، وأي عميل متوافق مع MCP يمكنه استدعاؤه. في هذا الدليل تبني خادمًا بأداتين (آلة حاسبة add ومساعد fetch_url)، وتشغّله محليًا عبر stdio، وتختبره، وتوصله بعميل حقيقي.

إليك كل ما تحتاجه قبل أن تبدأ.

كلا المسارين ينتج خادمًا بسلوك متطابق. اختر اللغة التي يعمل بها فريقك بالفعل. إن لم يكن لديك تفضيل، ابدأ بـ Python، لأن FastMCP يجعل الخادم الأول أقصر.

ما الذي يكشفه خادم MCP فعليًا؟

قبل كتابة الكود، يساعد معرفة الأشياء الثلاثة التي يمكن للخادم تقديمها. يكشف خادم MCP أدوات (دوال يمكن للنموذج استدعاؤها، مثل "استعلم عن قاعدة البيانات")، وموارد (بيانات للقراءة فقط يمكن للنموذج تحميلها، مثل ملف أو سجل)، ومطالبات (قوالب مطالبات قابلة لإعادة الاستخدام). معظم الخوادم التي ستبنيها ستكون مكثفة الأدوات؛ والموارد والمطالبات اختيارية.

خادم MCP، تعريفه: عملية تتحدث بروتوكول Model Context Protocol وتُعلن قائمة من الأدوات والموارد والمطالبات التي يمكن لعميل ذكاء اصطناعي اكتشافها واستدعاؤها في وقت التشغيل.

يعمل العميل (Claude Desktop مثلًا) كمضيف. يشغّل خادمك أو يتصل به، ويسأل "ما الأدوات التي لديك؟"، ثم يستدعيها عندما يقرر النموذج أن أداة ما مفيدة. أنت لا تستدعي النموذج من داخل الخادم أبدًا. التدفق يسير في الاتجاه الآخر.

هذا الاتجاه مهم. خادمك مزوّد سلبي. ينتظر اتصال العميل، ويجيب طلب الاكتشاف، ويشغّل الأداة المستدعاة. احتفظ بهذا النموذج الذهني، وسيتضح بقية الدليل من تلقاء نفسه.

كيفية بناء خادم MCP بلغة Python (خطوة بخطوة)

Python هو أسرع طريق إلى خادم قيد التشغيل، لأن FastMCP يتولى سباكة البروتوكول ويحوّل الدوال البسيطة إلى أدوات عبر مُزخرِف. كل ما يلي يستخدم الـ SDK الرسمي للغة Python. إليك الخطوات الأربع.

الخطوة 1: إعداد المشروع. استخدم uv، الذي أصبح المعيار لمشاريع MCP بلغة Python:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

إن فضّلت pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

الخطوة 2: كتابة الخادم. أنشئ server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

أمران ينبغي ملاحظتهما. تصبح سلسلة التوثيق (docstring) وصف الأداة الذي يقرأه النموذج، فاكتبها كتعليمة. وتصبح تلميحات الأنواع (a: int) تلقائيًا مخطط الإدخال، فيولّد FastMCP مخطط JSON نيابة عنك.

الخطوة 3: تشغيله. يبدأ mcp.run() الخادم عبر stdio، وهو وسيلة النقل التي يشغّلها العملاء محليًا. أنت لا تشغّل هذا مباشرة أثناء التطوير؛ العميل هو من يشغّله. لاختبار سريع، استخدم مشغّل التطوير:

uv run mcp dev server.py

الخطوة 4: إعادة مخرجات نظيفة. فخ يستحق التنبيه إليه الآن: أعِد سلسلة نصية أو قيمة ذات نوع، لا قاموسًا متداخلًا على أمل أن يُعرض. سنعود إلى السبب في قسم الإنتاج، لكن باختصار قد تُقتطع أنواع الإرجاع الغامضة بصمت في بعض العملاء.

هذا خادم MCP كامل بلغة Python. أداتان، استدعاءات شبكة حقيقية، مخطط تلقائي. تاليًا الشيء نفسه بلغة TypeScript.

كيفية بناء خادم MCP بلغة TypeScript (خطوة بخطوة)

يستخدم مسار TypeScript الـ SDK الرسمي للغة TypeScript مباشرة، وzod للتحقق من الإدخال. وهو أكثر إسهابًا قليلًا من FastMCP، لكن الأنواع ممتازة وينشر بنظافة إلى مضيفات Node.

الخطوة 1: إعداد المشروع.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

الخطوة 2: كتابة الخادم. أنشئ server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

الخطوة 3: تشغيله. أثناء التطوير: npx tsx server.ts. للإنتاج، اِبنِ باستخدام tsc وشغّل ملف .js المبني عبر Node. لاحظ شكل الإرجاع: تُعيد كل أداة { content: [{ type: "text", text: ... }] }. هذا المصفوف content الصريح هو مكافئ TypeScript لقاعدة "أعِد سلسلة نظيفة" من Python. يريد الـ SDK كتل محتوى ذات أنواع، لا كائنات خام.

الخطوة 4: التحقق من الإدخال باستخدام zod. يرفض المخطط z.string().url() الإدخال غير الصالح قبل تشغيل معالِجك، وهو بالضبط ما تريده عندما يولّد النموذج الوسائط.

الأداتان نفساهما، السلوك نفسه، TypeScript اصطلاحي. لنقرر الآن كيف ينبغي للعملاء الوصول إلى خادمك.

stdio مقابل Streamable HTTP: أي وسيلة نقل يجب أن تستخدم؟

تتحدث خوادم MCP عبر إحدى وسيلتي نقل. stdio يشغّل الخادم كعملية فرعية محلية يطلقها العميل ويتواصل معها عبر الإدخال/الإخراج القياسي. Streamable HTTP يشغّل الخادم كخدمة شبكية يتصل بها العملاء عبر HTTP. اختر بناءً على المكان الذي يجب أن يعيش فيه الخادم.

القاعدة العملية: اِبنِ واختبر على stdio، وانتقل إلى Streamable HTTP فقط عندما يحتاج أكثر من شخص أو جهاز إلى الخادم. معظم الخوادم لا تحتاج أبدًا إلى مغادرة stdio. الاستدعاءان mcp.run() وStdioServerTransport() أعلاه هما stdio بالفعل، فأنت جاهز للتطوير.

كيفية اختبار خادم MCP باستخدام Inspector

قبل دمج خادمك في Claude، اختبره معزولًا باستخدام MCP Inspector. هو واجهة متصفح تتصل بخادمك، وتسرد أدواته، وتتيح لك استدعاءها يدويًا. شغّله مقابل خادمك:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

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

كيفية ربط خادم MCP بـ Claude Desktop وClaude Code وCursor

بمجرد رضا Inspector، وجّه عميلًا حقيقيًا إلى خادمك. يقرأ كل عميل ملف إعداد يخبره كيف يُطلق خادمك عبر stdio.

Claude Desktop. حرّر claude_desktop_config.json (على macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

أعِد تشغيل Claude Desktop فتظهر أدواتك تحت أيقونة الموصِّلات.

Claude Code. أضف الخادم بأمر واحد من مشروعك: claude mcp add demo-server -- uv run server.py. يخزّنه Claude Code في إعداد مشروعك ويحمّله عند الإطلاق. إن كنت تستخدم أيضًا الـ hooks لبرمجة Claude Code، فإن دليلنا حول hooks في Claude Code يتناسب جيدًا مع أدوات MCP المخصصة.

Cursor. أضف كتلة mcpServers نفسها إلى .cursor/mcp.json في جذر المشروع. الشكل يطابق شكل Claude Desktop. لمثال واقعي على خادم MCP يعمل داخل Claude Code، اطّلع على كيفية ربطنا Higgsfield في Claude Code.

استخدم مسارات مطلقة في كل إعداد. المسارات النسبية هي السبب الأكثر شيوعًا لعدم بدء الخادم.

نشر خادم MCP إلى الإنتاج (المصادقة والاستضافة)

عندما يحتاج خادمك إلى المشاركة، انقله من stdio إلى Streamable HTTP وأضف ثلاثة أشياء: المصادقة، ومعالجة الأخطاء، ومضيفًا.

• المصادقة. يجب أن تستخدم خوادم MCP البعيدة OAuth 2.1 وفق مواصفة تفويض MCP. للأدوات الداخلية، يُعدّ فحص رمز bearer على نقطة نهاية HTTP الحد الأدنى العملي. لا تنشر أبدًا خادم أدوات عامًا غير مُصادَق عليه، لأن أداة تشغّل SQL أو تصل إلى واجهات برمجية داخلية هي سطح هجوم نشط.
• معالجة الأخطاء. غلّف أجسام الأدوات بـ try/except (أو try/catch) وأعِد رسالة خطأ ذات نوع بدل رمي استثناء. يتعامل النموذج مع "فشل الاستعلام، وإليك السبب" أفضل بكثير من اتصال مقطوع.
• الاستضافة. أي منصة تشغّل عملية Node أو Python طويلة العمر تفي بالغرض: VPS صغير، أو Fly.io، أو Railway، أو حاوية على بنيتك التحتية. أبقِ العملية دافئة، لأن البدايات الباردة تضيف زمن استجابة إلى أول استدعاء أداة.
• التزامن والتكلفة. إذا كانت أدواتك تستدعي نموذج LLM أو واجهة برمجية مدفوعة لاحقًا، فضع بوابة أمامها. تغطي نظرتنا العامة على أدوات بوابات LLM تحديد المعدل والرجوع الاحتياطي، وتساعد أدوات هندسة السياق في منع مخرجات الأدوات من تضخيم نافذة سياق النموذج.

للغة Python، غيّر استدعاء التشغيل إلى mcp.run(transport="streamable-http")؛ وللغة TypeScript، استبدل StdioServerTransport بـ StreamableHTTPServerTransport الخاص بالـ SDK. لا تتغير تعريفات الأدوات إطلاقًا. هذا هو جوهر تجريد النقل.

ما تعلّمناه من إطلاق خوادم MCP في الإنتاج

في Techsy بنينا خوادم MCP للاستخدام الداخلي، وبعض الدروس لا تظهر إلا عندما تصطدم بها حركة مرور حقيقية. إليك ما قِسناه وأين لُدغنا.

أول خادم أطلقناه كان أداة استعلام Postgres للقراءة فقط، بُنيت بـ FastMCP 2.x على الـ SDK لـ Python mcp 1.x، ثم أُعيدت كتابتها بـ @modelcontextprotocol/sdk 1.x للمقارنة. على مجموعة تقنية من 2026 (Node 20، Python 3.11)، أضافت استدعاءات الأدوات المحلية عبر stdio نحو 8 إلى 12 مللي ثانية من نفقات النقل لكل استدعاء. بمجرد نقل الخادم نفسه إلى Streamable HTTP على VPS، ارتفعت الكلفة لكل استدعاء إلى 40 إلى 70 مللي ثانية، معظمها ذهاب وإياب عبر الشبكة لا كلفة بروتوكول. كانت بداية FastMCP الباردة نحو 300 مللي ثانية للعملية، ولهذا نبقي عملية الإنتاج دافئة.

الفخ الذي كلّفنا نحو ساعتين: أداة أعادت قاموس Python خامًا عُرضت جيدًا في Inspector لكنها عادت مقتطعة داخل Claude Desktop. تغليف قيمة الإرجاع كسلسلة نصية ذات نوع أصلح ذلك فورًا. لهذا يُعيد هذا الدليل في كل مكان سلاسل نصية وكتل نص content بدل كائنات متداخلة. العادة الأخرى التي أتت بثمارها فورًا كانت تمرير كل خادم عبر npx @modelcontextprotocol/inspector قبل لمس أي إعداد عميل، ما كشف مخطط إدخال مشوّهًا في إعادة كتابة TypeScript كان سيفشل بصمت في Cursor.

إذا كنت تختار الأدوات التي تبنيها في خوادم من الأساس، فإن قائمتنا لـ أفضل خوادم MCP لعام 2026 بنك أفكار جيد.

كيف تتعامل Techsy مع تطوير MCP

في Techsy نبني خوادم MCP كجزء من أنظمة وكلاء الذكاء الاصطناعي التي نسلّمها للعملاء، فنربط الوكلاء بقواعد بيانات داخلية وأنظمة CRM وواجهات برمجية عبر طبقة أدوات ذات أنواع. نهجنا هو أن نبدأ ضيقًا (أداة واحدة مُختبَرة جيدًا عبر stdio)، ونتحقق منها في Inspector، ثم نرقّيها إلى خدمة HTTP مُصادَق عليها فقط عندما يحتاجها أكثر من وكيل. نقرن الخوادم المخصصة بـ Claude Agent SDK عندما يصبح منطق الوكيل معقدًا.

إليك النسخة الصادقة: معظم الفرق تُفرط في بناء خادمها الأول. نادرًا ما تحتاج إلى HTTP وOAuth واثنتي عشرة أداة في اليوم الأول. إن أردت زوجًا ثانيًا من العيون على تكامل MCP، احصل على استشارة مجانية وسنخبرك إن كان عمل stdio بأداة واحدة أم شيئًا يحتاج بنية تحتية حقًا.

الأسئلة الشائعة

هل أبني خادم MCP بلغة Python أم TypeScript؟

استخدم اللغة التي يعمل بها فريقك بالفعل. Python مع FastMCP هو أقصر طريق إلى أول خادم قيد التشغيل، لأن مُزخرِفًا يحوّل دالة إلى أداة. TypeScript مع الـ SDK الرسمي أكثر إسهابًا قليلًا لكنه يمنحك أنواعًا ممتازة وينشر بنظافة إلى مضيفات Node. كلاهما ينتج خوادم تتصرف بشكل متطابق بالنسبة للعميل.

هل أحتاج إطار عمل مثل FastMCP لبناء خادم MCP؟

لا، لكنه يساعد. يأتي FastMCP ضمن الـ SDK الرسمي لـ Python mcp ويزيل معظم الكود التكراري للبروتوكول. يمكنك استخدام واجهة Server الأدنى مستوى لتحكم دقيق، لكن لأي خادم تقريبًا يكون FastMCP (Python) أو McpServer (TypeScript) الأداة الصحيحة وكودًا أقل بكثير.

كيف أصحّح خادم MCP لا يعمل؟

مرّره أولًا عبر MCP Inspector: npx @modelcontextprotocol/inspector متبوعًا بأمر التشغيل لديك. يسرد Inspector أدواتك ويتيح لك استدعاءها مباشرة، فتؤكد أن الخادم يعمل قبل لوم العميل. إن كان Inspector سليمًا والعميل ليس كذلك، فتحقق من أن إعدادك يستخدم مسارات مطلقة وأنك أعدت تشغيل العميل.

هل FastMCP جزء رسمي من MCP؟

نعم. يأتي FastMCP مع الـ SDK الرسمي لـ Python في Model Context Protocol كواجهة خادم عالية المستوى. المُزخرِف @mcp.tool() الذي تستخدمه هو الطريقة المُوصى بها لبناء خوادم Python، وليس إضافة من طرف ثالث.

ما الفرق بين خادم MCP محلي وآخر بعيد؟

يعمل الخادم المحلي على جهازك عبر stdio، يطلقه العميل كعملية فرعية، وهو الأفضل للأدوات الشخصية والتطوير. يعمل الخادم البعيد كخدمة ويب عبر Streamable HTTP ويمكن لعملاء متعددين الوصول إليه، ما يتطلب مصادقة OAuth 2.1. اِبنِ محليًا أولًا، وانتقل إلى البعيد فقط عند المشاركة.

بأي لغات يمكنني بناء خادم MCP؟

لدى Model Context Protocol أطقم SDK رسمية للغات Python وTypeScript وJava وKotlin وC#، مع أطقم SDK مجتمعية بلغات أخرى. ولأن MCP بروتوكول سلكي، يمكن لأي لغة قادرة على قراءة وكتابة JSON-RPC عبر stdio أو HTTP أن تنفّذ خادمًا، لكن الأطقم الرسمية توفّر عليك ذلك العمل.

هل يعمل خادم MCP مع ChatGPT وGemini أم مع Claude فقط؟

MCP معيار مفتوح مُعتمَد عبر نظام الذكاء الاصطناعي الوكيل بأكمله، بما في ذلك ChatGPT وGemini وCursor وVS Code Copilot. خادم واحد تبنيه يعمل مع أي عميل متوافق. أنت لا تكتب تكاملًا منفصلًا لكل نموذج، وهذا هو جوهر البروتوكول.

كم يستغرق بناء خادم MCP فعّال؟

يستغرق أول خادم بأداة أو أداتين عبر stdio نحو 15 دقيقة بمجرد تثبيت بيئة التشغيل لديك. قِسنا 14 دقيقة لمبتدئ على Node 20 وأقل من 5 دقائق لبناء متكرر. المصادقة ونقل HTTP واستضافة الإنتاج هي ما يستغرق وقتًا حقيقيًا، لا الخادم نفسه.

عن الكاتب

مرت باتور هو المؤسس المشارك لـ Techsy.io، حيث يسلّم الفريق وكلاء ذكاء اصطناعي وأنظمة أتمتة وخطوط أنابيب صوتية/SDR لعملاء B2B. يكتب عن مجموعة أدوات LLM التي يستخدمها فريق Techsy فعليًا في الإنتاج. تواصل عبر LinkedIn.

*مرت باتور، المؤسس المشارك، Techsy.io