رفتن به محتوا

اتصال به سرورهای MCP

افزودن یک سرور MCP به Claude Code، بررسی اتصال، و یافتنِ پیکربندی روی دیسک.

Model Context Protocol (MCP) به Claude Code اجازه می‌دهد از ابزارهایی فراتر از مجموعه‌ی داخلی‌اش استفاده کند؛ مثلاً جست‌وجو در یک ردیابِ مسائل، کوئری‌زدن به یک پایگاه‌داده، یا کنترلِ یک مرورگر وب. این ابزارها از سرورهای MCP می‌آیند که روی دستگاه تو اجرا می‌شوند یا به‌صورتِ سرویس‌های میزبانی‌شده.

این راهنما تو را گام‌به‌گام در اتصالِ یک سرور MCP، از ابتدا تا انتها، با CLIِ Claude Code همراهی می‌کند. در پایان، یک سرورِ متصل و پاسخ‌گو خواهی داشت، می‌دانی پیکربندی‌اش کجای دیسک ذخیره می‌شود، و بلدی رایج‌ترین خطاهای اتصال را برطرف کنی.

برای دیدنِ همه‌ی راه‌های اتصال و پیکربندیِ سرورهای MCP در Claude Code، به مرجعِ MCP سر بزن.

مطمئن شو که این‌ها را داری:

  • نصبِ Claude Code و احرازِهویت‌شده
  • یک ترمینالِ باز در یک پوشه‌ی پروژه. هر پوشه‌ای کار می‌کند، حتی یک پوشه‌ی خالی.

افزودن و بررسیِ یک سرور

Section titled “افزودن و بررسیِ یک سرور”

مثالِ زیر به سرور MCP مستنداتِ Claude Code متصل می‌شود؛ یک سرورِ میزبانی‌شده با جست‌وجوی متن‌کاملِ روی مستنداتِ Claude Code. این سرور نیاز به احرازِهویت یا پیکربندیِ خاصی ندارد، پس برای تستِ جریانِ راه‌اندازی، سرورِ اولِ خوبی است.

گام‌ها برای هر سروری یکسان است: اضافه‌اش کن، وضعیتِ اتصال را بررسی کن، سپس در یک نشست از آن استفاده کن، با یک گامِ پاک‌سازیِ اختیاری در انتها. بعضی سرورها یک گام اضافه دارند، مثلِ ورود از طریقِ مرورگر، که در نمونه‌های بیشترِ سرورِ MCP نشان داده شده. برای سرورهای بیشتر، فهرستِ Anthropic را مرور کن.

افزودنِ سرور MCP

سرور را در Claude Code ثبت کن. این را در ترمینالت اجرا کن، نه داخلِ یک نشستِ claude: تو پیش از شروعِ گفت‌وگو، در حالِ پیکربندیِ سرور هستی.

Terminal window
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

اجزای این دستور:

  • claude mcp add: یک سرور را در Claude Code ثبت می‌کند.
  • --transport http: سرور روی یک URL میزبانی شده، نه این‌که به‌صورتِ یک فرایندِ محلی اجرا شود.
  • claude-code-docs: نامی که خودت می‌سازی. اگر همان سرور را docs بنامی، عیناً همان‌طور کار می‌کند. Claude Code از هر نامی که انتخاب کنی استفاده می‌کند تا ابزارهای سرور را در خروجیِ Claude برچسب بزند و در دستورهایی مثلِ claude mcp remove به سرور ارجاع دهد.
  • https://code.claude.com/docs/mcp: آدرسِ URL که سرور روی آن میزبانی شده.

دستور یک تأییدیه چاپ می‌کند، چیزی شبیهِ Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config. بخشِ local config یعنی سرور برای تو، در همین پروژه، ثبت شده است: اگر Claude Code را در پروژه‌ی دیگری شروع کنی، این سرور آن‌جا فعال نیست. برای ثبتِ یک سرور به‌صورتِ یک‌باره برای همه‌ی پروژه‌هایت، آن را در دامنه‌ی کاربر (user scope) اضافه کن، که در تغییرِ دامنه‌ی سرور پوشش داده شده.

بررسیِ وضعیتِ اتصال

تأیید کن که سرور در فهرستِ سرورهایت ظاهر می‌شود و وضعیتش را بررسی کن:

Terminal window
claude mcp list

سرور همراه با یک نشانگرِ وضعیت ظاهر می‌شود:

وضعیتمعنا
✓ Connectedآماده‌ی استفاده. این همان چیزی است که باید برای claude-code-docs ببینی
! Needs authenticationسرور در دسترس است اما به ورود از طریقِ مرورگر، یا یک توکن که با --header پاس داده شود، نیاز دارد. ببین اتصالِ سروری که نیاز به ورود دارد
✗ Failed to connectسرور پاسخ نداد. ببین عیب‌یابی
✗ Connection errorتلاش برای اتصال یک خطا انداخت. ببین عیب‌یابی
⏸ Pending approvalیک سرورِ در دامنه‌ی پروژه که هنوز تأییدش نکرده‌ای. ببین ویرایشِ مستقیمِ .mcp.json

استفاده از سرور

یک نشست شروع کن و از Claude بخواه سرور تازه را با نامش به کار بگیرد:

Terminal window
claude
Use the claude-code-docs server to look up what MCP_TIMEOUT does

اولین باری که Claude سرور را فرامی‌خواند، برای استفاده از ابزارِ تازه درخواستِ مجوز می‌کند. برای ادامه، تأییدش کن. فراخوانیِ ابزار در خروجیِ Claude با نامِ سرور برچسب می‌خورد، و همین است که تأیید می‌کند پاسخ از سرورِ MCP آمده، نه از دانشِ داخلیِ Claude.

حذفِ سرور

این گام اختیاری است. وقتی آزمایش‌کردنت تمام شد، می‌توانی سرور را حذف کنی:

Terminal window
claude mcp remove claude-code-docs

سرورها کجا ذخیره می‌شوند

Section titled “سرورها کجا ذخیره می‌شوند”

دستورِ claude mcp add جزئیاتِ سرور را در یک فایلِ پیکربندی می‌نویسد. به‌صورتِ پیش‌فرض، سرور را در دامنه‌ی local ثبت می‌کند: خصوصی برای تو، فعال فقط در پروژه‌ی فعلی. برای ثبتِ یک‌باره‌ی آن برای همه‌ی پروژه‌هایت --scope user را پاس بده، یا برای به‌اشتراک‌گذاری با هم‌تیمی‌هایت --scope project. تغییرِ دامنه‌ی سرور هر دو را گام‌به‌گام توضیح می‌دهد.

راه‌های دیگری هم برای افزودنِ سرور هست، که هرکدام در ادامه‌ی همین صفحه پوشش داده شده‌اند:

یافتنِ پیکربندی روی دیسک

Section titled “یافتنِ پیکربندی روی دیسک”

دستورِ claude mcp add بسته به پرچمِ --scope، سرور را در یکی از سه دامنه می‌نویسد که در دو فایل ذخیره می‌شوند. لازم نیست این فایل‌ها را مستقیم ویرایش کنی، اما دانستنِ جای‌شان به اشکال‌زدایی و کنترلِ نسخه کمک می‌کند.

دامنهفایلدر دسترسِ
local~/.claude.json، زیرِ ورودیِ مربوط به این پروژهفقط تو، فقط این پروژه. پیش‌فرض
project.mcp.json در ریشه‌ی پروژه‌اتهر کسی که پروژه را clone کند
user~/.claude.json، زیرِ کلیدِ سطح‌بالای mcpServersفقط تو، همه‌ی پروژه‌ها

روی ویندوز، ~/.claude.json به %USERPROFILE%\.claude.json تبدیل می‌شود، که معمولاً C:\Users\YourName\.claude.json است. اگر CLAUDE_CONFIG_DIR را تنظیم کرده باشی، Claude Code به‌جای آن .claude.json را از داخلِ آن پوشه می‌خواند.

برای دیدنِ این‌که تعریفِ یک سرور در کدام دامنه است، claude mcp get claude-code-docs را اجرا کن. برای این‌که وقتی همان سرور در بیش از یک دامنه تعریف شده، دامنه‌ها چطور با هم تعامل می‌کنند، ببین دامنه‌های نصبِ MCP.

دامنه‌ی یک سرور هنگامِ افزودن ثابت می‌شود، پس تغییرِ دامنه یعنی حذفِ ورودی و افزودنِ دوباره‌ی آن در دامنه‌ی جدید. هر دو حالتِ زیر با حذفِ ورودیِ محلی از راهنماییِ اول شروع می‌شوند، تا سرور فقط یک تعریف داشته باشد. اگر در پایانِ آن راهنمایی قبلاً حذفش کرده‌ای، از این دستور رد شو:

Terminal window
claude mcp remove claude-code-docs --scope local

استفاده از یک سرور در همه‌ی پروژه‌هایت

Section titled “استفاده از یک سرور در همه‌ی پروژه‌هایت”

سرور را در دامنه‌ی user دوباره اضافه کن تا در هر پروژه‌ای که باز می‌کنی فعال باشد، و همچنان خصوصی برای تو بماند:

Terminal window
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

به‌اشتراک‌گذاری یک سرور با تیمت

Section titled “به‌اشتراک‌گذاری یک سرور با تیمت”

سرور را در دامنه‌ی project دوباره اضافه کن، که در .mcp.json در ریشه‌ی پروژه نوشته می‌شود:

Terminal window
claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

.mcp.json را در کنترلِ نسخه کامیت کن. هم‌تیمی‌هایی که مخزن را clone می‌کنند و Claude Code را شروع می‌کنند، یک پرامپت برای تأییدِ سرور می‌بینند، و بعد برای آن‌ها هم متصل می‌شود.

نمونه‌های بیشترِ سرورِ MCP

Section titled “نمونه‌های بیشترِ سرورِ MCP”

راهنماییِ اول از یک سرورِ میزبانی‌شده استفاده کرد که بدونِ هیچ ورودی متصل می‌شود. مثال‌های زیر دو شکلِ رایجِ دیگر را پوشش می‌دهند، با همان جریانِ افزودن، بررسی، استفاده.

یک سرورِ محلیِ stdio برنامه‌ای است که Claude Code آن را به‌صورتِ یک زیرفرایند روی دستگاهت اجرا می‌کند، نه سرویسی که از طریقِ یک URL به آن می‌رسد. از آن برای ابزارهایی استفاده کن که به منابعِ محلی مثلِ یک مرورگر، فایل‌سیستمت، یا یک سوکتِ پایگاه‌داده نیاز دارند.

سرور MCP Playwright یکی از گزینه‌های خوب برای امتحان است: به Claude یک مرورگر می‌دهد که می‌تواند در آن پیمایش، کلیک و خواندن کند، و به هیچ حسابی نیاز ندارد. از طریقِ npx اجرا می‌شود، پس به Node.js نسخه‌ی ۱۸ یا بالاتر نیاز دارد.

افزودنِ سرور Playwright

سرور را همراه با دستوری که Claude Code باید برای شروعِ آن اجرا کند ثبت کن:

Terminal window
claude mcp add playwright -- npx -y @playwright/mcp@latest

این دستور از سه نظر با مثالِ میزبانی‌شده فرق دارد:

  • پرچمِ --transport نیست، چون سرورهای محلی از انتقالِ پیش‌فرضِ stdio استفاده می‌کنند.
  • هر چیزی پس از جداکننده‌ی -- همان دستوری است که Claude Code برای شروعِ سرور اجرا می‌کند.
  • -y به npx می‌گوید بسته را بدونِ پرسش نصب کند.

Playwright هر Chromeی را که از قبل روی دستگاهت نصب باشد به کار می‌گیرد. برای استفاده از مرورگرِ دیگر، پس از @playwright/mcp@latest پرچمِ --browser را همراه با نامِ مرورگر بیاور، مثلاً --browser firefox.

بررسیِ اتصال

تأییدیه‌ی Added یعنی ورودی ذخیره شد، نه این‌که دستور اجرا می‌شود. اتصال را بررسی کن:

Terminal window
claude mcp list

اولین بررسی ممکن است ✗ Failed to connect را نشان دهد در حالی که npx دارد بسته را دانلود می‌کند، پس کمی صبر کن و دوباره اجرایش کن.

استفاده از مرورگر

کاری به Claude بده که به مرورگر نیاز دارد:

Use playwright to open https://example.com and tell me the page title

یک پنجره‌ی مرورگر باز می‌شود تا بتوانی کارکردنش را تماشا کنی، و فراخوانی‌های ابزار در خروجیِ Claude با نامِ سرورِ playwright و عملِ موردِنظر، مثلِ browser_navigate، برچسب می‌خورند.

امتحان کن آن را به سرورِ توسعه‌ی محلی‌ات نشانه بگیری تا بررسی کنی یک صفحه پس از یک تغییر هنوز درست رندر می‌شود، یا از آن بخواه یک گزارشِ باگ را گام‌به‌گام طی کند.

اتصالِ سروری که نیاز به ورود دارد

Section titled “اتصالِ سروری که نیاز به ورود دارد”

سرویس‌های میزبانی‌شده مثلِ Sentry، Linear و Notion سرورهای MCPشان را پشتِ OAuth اجرا می‌کنند: تو URLِ سرور را اضافه می‌کنی، سپس از طریقِ مرورگرت وارد می‌شوی.

گام‌های زیر از Sentry به‌عنوانِ مثال استفاده می‌کنند. برای اتصالِ یک سرویسِ دیگر، URLِ آن را جایگزین کن، که می‌توانی در فهرستِ Anthropic یا مستنداتِ آن سرویس پیدایش کنی.

افزودنِ سرور

دستورِ add همان دستورِ سرورِ مستندات است، با URLِ Sentry:

Terminal window
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

پس از افزودن، claude mcp list سرور را با ! Needs authentication نشان می‌دهد. این انتظار می‌رفت: گامِ بعدی ورود را کامل می‌کند.

احرازِهویت در مرورگرت

یک نشستِ Claude Code شروع کن و پنلِ MCP را باز کن:

/mcp

از فهرست sentry را انتخاب کن، Enter بزن، و Authenticate را برگزین. مرورگرت صفحه‌ی ورودِ Sentry را باز می‌کند. اتصال را همان‌جا تأیید کن.

در Claude Code، وضعیتِ سرور به متصل تغییر می‌کند. اگر ورود شکست خورد یا مرورگر باز نشد، ببین عیب‌یابی.

استفاده از سرور

چیزی از Claude بپرس که به آن سرویس نیاز دارد، مثلِ What Sentry projects do I have access to?، و دنبالِ فراخوانی‌های ابزارِ برچسب‌خورده با نامِ سرورِ sentry در خروجی‌اش بگرد.

سرورهایی که به‌جای OAuth با یک توکنِ ایستا احرازِهویت می‌کنند، توکن را هنگامِ افزودن با --header "Authorization: Bearer <token>" می‌گیرند. برای یک نمونه‌ی کامل ببین مثالِ GitHub.

هر فایلی در جدولِ دامنه‌ها از همان قالبِ JSON برای ورودی‌های سرور استفاده می‌کند. این بخش .mcp.json را ویرایش می‌کند، یعنی فایلِ دامنه‌ی پروژه. این فایل بیش از همه ارزشِ نوشتن با دست را دارد، چون در مخزن کامیت می‌شود، جایی که هم‌زمان نقشِ پیکربندی‌به‌صورتِ‌کد را برای تیمت بازی می‌کند.

.mcp.json را در ریشه‌ی پروژه‌ات بساز. مثالِ زیر هر دو سرورِ این راهنما را تعریف می‌کند، سرورِ میزبانی‌شده‌ی مستندات که از طریقِ HTTP به آن می‌رسیم و سرورِ Playwright به‌صورتِ یک فرایندِ محلیِ stdio:

{
"mcpServers": {
"claude-code-docs": {
"type": "http",
"url": "https://code.claude.com/docs/mcp"
},
"playwright": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
}
}
}

فیلدها بسته به نوعِ سرور فرق می‌کنند:

  • برای سرورهای HTTP، url همان نقطه‌ی پایانی است که Claude Code به آن متصل می‌شود.
  • برای سرورهای stdio، command و args همان برنامه‌ای هستند که اجرا می‌کند.

پس از ذخیره‌ی فایل، یک نشستِ تازه‌ی Claude Code در پروژه شروع کن. Claude Code هنگامِ راه‌اندازی .mcp.json را می‌خواند.

اولین باری که Claude Code یک سرورِ در دامنه‌ی پروژه را می‌بیند، از تو می‌خواهد تأییدش کنی. این پرامپت برای آن است که مخزنی که clone می‌کنی نتواند بدونِ رضایتت روی دستگاهت فرایند راه بیندازد. پرامپت را تأیید کن، یا اگر از دستت در رفت، بعداً /mcp را اجرا کن تا تأییدش کنی.

پس از تأیید، /mcp را اجرا کن و بررسی کن که سرورها به‌صورتِ متصل نشان داده می‌شوند. اگر یکی به‌جایش خطا نشان داد، ببین عیب‌یابی.

این راهنما از دستورهای CLIِ claude mcp استفاده می‌کند، اما هر بسترِ Claude Code می‌تواند به سرورهای MCP متصل شود:

اگر سروری متصل نشد، وضعیتش را با /mcp داخلِ یک نشست یا claude mcp list از شِلت بررسی کن، سپس نشانه‌ی زیر را تطبیق بده. پنلِ /mcp این امکان را هم می‌دهد که بدونِ ترکِ نشست دوباره وصل شوی یا احرازِهویت کنی.

‏‎/mcp پیامِ No MCP servers configured را نشان می‌دهد

Claude Code هیچ سروری برای پوشه‌ی فعلی پیدا نکرد. رایج‌ترین دلایل:

  • تو claude mcp add را از یک پروژه‌ی دیگر اجرا کرده‌ای. سرورهای در دامنه‌ی محلی به پروژه‌ای که اضافه‌شان کرده‌ای گره خورده‌اند: ریشه‌ی مخزن، یا اگر در یک مخزنِ git نبودی، دقیقاً همان پوشه. سرور را از پروژه‌ای که الان در آن هستی دوباره اضافه کن، یا آن را با --scope user اضافه کن تا به یک پروژه گره نخورد.
  • یک فایلِ پیکربندی را در مسیرِ اشتباه ویرایش کرده‌ای. فایل‌های درست ~/.claude.json و <project>/.mcp.json هستند. Claude Code مسیرهایی مثلِ ~/.claude/config/mcp.json، ~/.claude/mcp.json، یا %APPDATA%\Claude\mcp.json را نمی‌خواند.
وضعیت Failed to connect یا Connection error را نشان می‌دهد

هر دو وضعیت یعنی سرور شروع نشد یا URL پاسخ نداد. این‌ها برای سرورهای HTTPی هم می‌توانند ظاهر شوند که به‌جای ورودِ مرورگری که در اتصالِ سروری که نیاز به ورود دارد پوشش داده شده، انتظارِ یک توکن دارند.

برای سرورهای HTTP، تأیید کن که URL از دستگاهت قابلِ‌دسترس است:

Terminal window
curl -I https://mcp.sentry.dev/mcp

در PowerShell به‌جای curl از curl.exe استفاده کن تا درخواست به جای نامِ مستعارِ Invoke-WebRequest به باینریِ واقعیِ curl برود.

پاسخ به تو می‌گوید با چه نوع مشکلی روبه‌رویی:

  • یک 404 یا 405: سرور بالا است. خیلی از نقطه‌های پایانیِ MCP فقط به درخواست‌های POST جواب می‌دهند، پس این هم تأیید می‌کند که URL از دستگاهت قابلِ‌دسترس است.
  • یک 401 یا 403: سرور بالا است و باید احرازِهویت کنی. از ورودِ مرورگری در اتصالِ سروری که نیاز به ورود دارد استفاده کن، یا برای سرورهایی که به‌جایش یک توکن می‌گیرند، مثلِ GitHub، آن را با --header "Authorization: Bearer <token>" پاس بده.
  • اصلاً پاسخی نیست: URL و شبکه‌ات را بررسی کن.

برای سرورهای stdio، دستورِ پیکربندی‌شده را مستقیم در ترمینالت اجرا کن تا خطای زیربنایی را ببینی. برای سرورِ Playwrightِ این راهنما، اجرا کن:

Terminal window
npx -y @playwright/mcp@latest

اتفاقِ بعدی به تو می‌گوید مشکل کجاست:

  • دستور شروع می‌شود و منتظرِ ورودی می‌ماند: خودِ سرور کار می‌کند. claude mcp get <name> را اجرا کن و تأیید کن دستوری که آن‌جا نشان داده می‌شود با چیزی که همین الان اجرا کردی یکی است. اگر دستورِ نشان‌داده‌شده با چیزی که تایپ کردی فرق دارد، احتمالاً جداکننده‌ی -- را پیش از دستورِ سرور جا انداخته‌ای. سرور را حذف کن و با -- در جای درستش دوباره اضافه‌اش کن. اگر .mcp.json را با دست نوشته‌ای، نحوْ و محلِ آن را بررسی کن.
  • دستور خطا می‌دهد: پیام می‌گوید چه چیزی کم است، مثلِ Node.js یا یک مرورگر.
اتصال هنگامِ راه‌اندازی به وقفه (timeout) خورد

سرور بیش از مهلتِ راه‌اندازیِ پیش‌فرضِ ۳۰ ثانیه طول کشید. اولین اجرای یک سرورِ stdio می‌تواند کند باشد چون npx دارد بسته را دانلود می‌کند. سقف را با متغیرِ محیطیِ MCP_TIMEOUT، برحسبِ میلی‌ثانیه، افزایش بده:

Terminal window
MCP_TIMEOUT=60000 claude

در PowerShell، متغیر را پیش از دستور در همان خط تنظیم کن:

Terminal window
$env:MCP_TIMEOUT = "60000"; claude
سرور از قبل وجود دارد

قبلاً یک سرور با همان نام در همان دامنه اضافه کرده‌ای. یا ابتدا ورودیِ موجود را حذف کن، یا نامِ دیگری انتخاب کن:

Terminal window
claude mcp remove claude-code-docs

اگر نام در بیش از یک دامنه وجود داشته باشد، remove پیامِ exists in multiple scopes را گزارش می‌کند. برای انتخابِ این‌که کدام نسخه حذف شود --scope را پاس بده، مثلاً claude mcp remove claude-code-docs --scope local.

سرور متصل می‌شود اما هیچ ابزاری ظاهر نمی‌شود

داخلِ یک نشست /mcp را اجرا کن و سرور را انتخاب کن تا فهرستِ ابزارهایش را ببینی. اگر فهرست خالی است، سرور شروع شده اما هیچ ابزاری ثبت نکرده، که معمولاً یعنی یک متغیرِ محیطیِ موردِنیاز مثلِ یک API key کم است.

متغیر را با --env KEY=value روی claude mcp add پاس بده، یا در فیلدِ env از ورودیِ .mcp.jsonِ سرور. مستنداتِ سرور متغیرهایی را که نیاز دارد فهرست می‌کند.

تغییراتِ .mcp.json اثر نمی‌کنند

Claude Code .mcp.json را هنگامِ شروعِ نشست می‌خواند. پس از ویرایشِ فایل، نشست را ببند و دوباره شروع کن.

اگر سرورهایت هنوز ظاهر نمی‌شوند، /mcp را اجرا کن و دنبالِ یک هشدارِ تجزیه (parse warning) بگرد. Claude Code ورودی‌های بدساخت را رد می‌کند و فیلدِ مشکل‌دار را همان‌جا نشان می‌دهد.

اگر قبلاً هنگامِ پرسش سرور را رد کرده‌ای، تأییدهای پروژه را بازنشانی کن:

Terminal window
claude mcp reset-project-choices
ورودِ OAuth شکست می‌خورد یا مرورگر باز نمی‌شود

/mcp را اجرا کن، سرور را انتخاب کن، و دوباره Authenticate را برگزین. اگر مرورگر به‌صورتِ خودکار باز نشد، URLِ نشان‌داده‌شده در ترمینال را کپی کن و دستی بازش کن. برای پورت‌های callbackِ ثابت و اعتبارهای ازپیش‌پیکربندی‌شده ببین احرازِهویت با سرورهای MCP از راه دور.

حالا که یک سرور متصل است، باقیِ چیزهایی را که MCP ممکن می‌کند کاوش کن: