mcp-remote

اربط عميل MCP يدعم الخوادم المحلية (stdio) فقط بخادم MCP بعيد، مع دعم المصادقة:

ملاحظة: هذا نموذج إثبات مفهوم (proof-of-concept) عملي لكن يجب اعتباره تجريبيًا.

لماذا نحتاج إلى هذا؟

حتى الآن، يُثبَّت معظم خوادم MCP المنتشرة محليًا باستخدام ناقل stdio. وهذا يحقق بعض الفوائد: يمكن لكل من العميل والخادم أن يثقا ببعضهما ضمنيًا لأن المستخدم منحهما الإذن بالتشغيل. ويمكن إضافة الأسرار مثل مفاتيح API باستخدام متغيرات البيئة دون أن تغادر جهازك أبدًا. كما أن البناء على npx وuvx مكّن المستخدمين من تجنّب خطوات التثبيت الصريحة أيضًا.

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

مع أحدث مواصفات التفويض الخاصة بـ MCP، أصبح لدينا الآن طريقة آمنة لمشاركة خوادم MCP مع العالم دون تشغيل تعليمات برمجية على أجهزة المستخدمين المحمولة. أو على الأقل، سيكون ذلك ممكنًا لو كانت جميع عملاء MCP الشهيرة تدعمها بالفعل. معظمها يدعم stdio فقط، وتلك التي تدعم HTTP+SSE لا تدعم بعد تدفقات OAuth المطلوبة.

من هنا تأتي أهمية mcp-remote. بمجرد أن يدعم عميل MCP الذي اخترته الخوادم البعيدة المفوَّضة، يمكنك إزالته. وإلى ذلك الحين، أضف هذا الأمر المكوّن من سطر واحد واستعد لعملاء MCP الذين تريدهم!

الاستخدام

تستخدم جميع عملاء MCP الأكثر شيوعًا (Claude Desktop وCursor وWindsurf) تنسيق الإعدادات التالي:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

الترويسات المخصصة

لتجاوز المصادقة، أو لإرسال ترويسات مخصصة مع جميع الطلبات إلى خادمك البعيد، مرّر وسائط --header عبر سطر الأوامر:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

ملاحظة: لدى Cursor وClaude Desktop (ويندوز) خطأ برمجي لا يتم فيه تخطي المسافات داخل args عند استدعاء npx، مما يؤدي إلى إفساد هذه القيم. يمكنك تجاوز ذلك باستخدام:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

الخيارات (Flags)

• إذا كان npx يُنتج أخطاءً، ففكّر في إضافة -y كوسيطة أولى لقبول تثبيت حزمة mcp-remote تلقائيًا.

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• لإجبار npx على التحقق دائمًا من وجود نسخة محدّثة من mcp-remote، أضف خيار @latest:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• لتغيير المنفذ الذي يستمع عليه mcp-remote لإعادة توجيه OAuth (افتراضيًا 3334)، أضف وسيطة إضافية بعد عنوان الخادم. لاحظ أنه مهما كان المنفذ الذي تحدده، إذا كان غير متاح فسيتم اختيار منفذ مفتوح عشوائيًا.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• لتغيير المضيف الذي يسجّله mcp-remote كعنوان URL لاستدعاء OAuth (افتراضيًا localhost)، أضف خيار --host.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• للسماح باتصالات HTTP في الشبكات الخاصة الموثوقة، أضف خيار --allow-http. ملاحظة: يجب استخدامه فقط في الشبكات الخاصة الآمنة حيث لا يمكن اعتراض حركة المرور.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• لتفعيل سجلات تصحيح أخطاء مفصّلة، أضف خيار --debug. سيكتب هذا سجلات مطوّلة إلى ~/.mcp-auth/{server_hash}_debug.log مع طوابع زمنية ومعلومات مفصّلة عن عملية المصادقة والاتصالات وتحديث الرموز.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• لتفعيل وكيل HTTP(S) صادر لـ mcp-remote، أضف خيار --enable-proxy. عند تفعيله، سيستخدم mcp-remote إعدادات الوكيل من متغيرات البيئة الشائعة (مثل HTTP_PROXY وHTTPS_PROXY وNO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• لتجاهل أدوات محددة من الخادم البعيد، أضف خيار --ignore-tool. سيؤدي هذا إلى استبعاد الأدوات المطابقة للأنماط المحددة من استجابات tools/list وحظر طلبات tools/call. يدعم أنماط أحرف البدل باستخدام *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

يمكنك تحديد عدة خيارات --ignore-tool لتجاهل أنماط مختلفة. أمثلة:

• delete* - يتجاهل جميع الأدوات التي تبدأ بـ "delete" (مثل deleteTask وdeleteUser)
• *account - يتجاهل جميع الأدوات التي تنتهي بـ "account" (مثل getAccount وupdateAccount)
• exactTool - يتجاهل فقط الأداة المسماة حرفيًا "exactTool"

• لتغيير مهلة انتظار استدعاء OAuth (افتراضيًا 30 ثانية)، أضف خيار --auth-timeout بقيمة بالثواني. وهذا مفيد إذا كانت عملية المصادقة على جانب الخادم تستغرق وقتًا طويلاً.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

استراتيجيات النقل

يدعم MCP Remote استراتيجيات نقل مختلفة عند الاتصال بخادم MCP. يتيح لك هذا التحكم في ما إذا كان يستخدم أحداث الخادم المرسلة (SSE) أو نقل HTTP، وبأي ترتيب يجربها.

حدد استراتيجية النقل باستخدام خيار --transport:

npx mcp-remote https://example.remote/server --transport sse-only

الاستراتيجيات المتاحة:

• http-first (الافتراضي): يجرب نقل HTTP أولاً، ويعود إلى SSE إذا فشل HTTP بخطأ 404
• sse-first: يجرب نقل SSE أولاً، ويعود إلى HTTP إذا فشل SSE بخطأ 405
• http-only: يستخدم نقل HTTP فقط، ويفشل إذا كان الخادم لا يدعمه
• sse-only: يستخدم نقل SSE فقط، ويفشل إذا كان الخادم لا يدعمه

بيانات تعريف عميل OAuth الثابتة

يدعم MCP Remote توفير بيانات تعريف ثابتة لعميل OAuth بدلاً من استخدام القيم الافتراضية لـ mcp-remote. وهذا مفيد عند الاتصال بخوادم OAuth التي تتوقع معرّفات أو نطاقات صلاحيات (scopes) محددة للعميل/البرنامج.

قدّم بيانات تعريف العميل كسلسلة JSON أو كمسار ملف مسبوق بـ @ مع خيار --static-oauth-client-metadata:

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'

معلومات عميل OAuth الثابتة

وفقًا للمواصفات، يُشجَّع الخوادم - دون إلزام - على دعم تسجيل العميل الديناميكي لـ OAuth.

بالنسبة لهذه الخوادم، يدعم MCP Remote توفير معلومات ثابتة لعميل OAuth بدلاً من ذلك. وهذا مفيد عند الاتصال بخوادم OAuth التي تتطلب عملاء مسجّلين مسبقًا.

قدّم معلومات العميل كسلسلة JSON أو كمسار ملف مسبوق بـ @ مع خيار --static-oauth-client-info:

export MCP_REMOTE_CLIENT_ID=xxx
export MCP_REMOTE_CLIENT_SECRET=yyy
npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude Desktop

الوثائق الرسمية

لإضافة خادم MCP إلى Claude Desktop، تحتاج إلى تعديل ملف الإعدادات الموجود في:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

إذا لم يكن موجودًا بعد، قد تحتاج إلى تفعيله من الإعدادات > المطور.

أعد تشغيل Claude Desktop ليلتقط التغييرات في ملف الإعدادات. بعد إعادة التشغيل، يجب أن ترى أيقونة مطرقة في الزاوية السفلية اليمنى من مربع الإدخال.

Cursor

الوثائق الرسمية. يقع ملف الإعدادات في ~/.cursor/mcp.json.

اعتبارًا من الإصدار 0.48.0، يدعم Cursor خوادم SSE غير الموثَّقة مباشرة. إذا كان خادم MCP لديك يستخدم بروتوكول تفويض MCP OAuth الرسمي، فلا تزال بحاجة إلى إضافة خادم "command" واستدعاء mcp-remote.

Windsurf

الوثائق الرسمية. يقع ملف الإعدادات في ~/.codeium/windsurf/mcp_config.json.

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

للحصول على إرشادات حول بناء ونشر خوادم MCP البعيدة، بما في ذلك العمل كعميل OAuth صالح، راجع الموارد التالية:

• https://developers.cloudflare.com/agents/guides/remote-mcp-server/

على وجه الخصوص، راجع:

• https://github.com/cloudflare/workers-oauth-provider لتعريف خادم OAuth متوافق مع MCP في Cloudflare Workers
• https://github.com/cloudflare/agents/tree/main/examples/mcp لتعريف McpAgent باستخدام إطار عمل agents.

لمزيد من المعلومات حول اختبار هذه الخوادم، راجع أيضًا:

• https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/

هل تعرف المزيد من الموارد التي تود مشاركتها؟ يرجى إضافتها إلى هذا الملف (Readme) وإرسال طلب سحب (PR)!

استكشاف الأخطاء وإصلاحها

امسح مجلد ~/.mcp-auth لديك

يخزّن mcp-remote جميع معلومات بيانات الاعتماد داخل ~/.mcp-auth (أو حيثما يشير MCP_REMOTE_CONFIG_DIR لديك). إذا كنت تواجه مشكلات مستمرة، فجرّب تشغيل:

rm -rf ~/.mcp-auth

ثم أعد تشغيل عميل MCP لديك.

تحقق من إصدار Node لديك

تأكد من أن إصدار Node المثبّت لديك هو 18 أو أعلى. سيستخدم Claude Desktop إصدار Node على نظامك، حتى لو كان لديك إصدار أحدث مثبّت في مكان آخر.

أعد تشغيل Claude

عند تعديل claude_desktop_config.json، قد يكون من المفيد إعادة تشغيل Claude بالكامل

شهادات VPN

قد تواجه مشكلات إذا كنت خلف VPN؛ يمكنك تجربة تعيين متغير البيئة NODE_EXTRA_CA_CERTS للإشارة إلى ملف شهادة CA. إذا كنت تستخدم claude_desktop_config.json، فقد يبدو الأمر كما يلي:

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

فحص السجلات

• تتبّع سجلات Claude Desktop في الوقت الفعلي
• MacOS / Linux:
  tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
• For bash on WSL:
  tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
• Powershell:
  Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

تصحيح الأخطاء

سجلات تصحيح الأخطاء

لاستكشاف المشكلات المعقدة، خاصة المتعلقة بتحديث الرموز أو مشكلات المصادقة، استخدم خيار --debug:

"args": [
  "mcp-remote",
  "https://remote.mcp.server/sse",
  "--debug"
]

ينشئ هذا سجلات مفصّلة في ~/.mcp-auth/{server_hash}_debug.log مع طوابع زمنية ومعلومات كاملة عن كل خطوة من خطوات الاتصال وعملية المصادقة. عندما تواجه مشكلات في تحديث الرموز، أو مشكلات سكون/استئناف الكمبيوتر المحمول، أو مشكلات مصادقة، قدّم هذه السجلات عند طلب الدعم.

أخطاء المصادقة

إذا واجهت الخطأ التالي، الذي يُرجعه عنوان /callback:

Authentication Error
Token exchange failed: HTTP 400

يمكنك تشغيل rm -rf ~/.mcp-auth لمسح أي حالة ورموز مخزّنة محليًا.

وضع "Client"

شغّل ما يلي في سطر الأوامر (وليس من خادم MCP):

npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse

سيُنفّذ هذا تدفق التفويض بالكامل ويحاول سرد الأدوات والموارد الموجودة في عنوان URL البعيد. جرّب هذا بعد تشغيل rm -rf ~/.mcp-auth لمعرفة ما إذا كانت بيانات الاعتماد القديمة هي مشكلتك؛ وإلا فمن المأمول أن تكون المشكلة أوضح في هذه السجلات مقارنة بتلك الموجودة في عميل MCP لديك.