شما میتوانید Chrome DevTools را برای عاملها پیکربندی کنید تا نحوه تعامل آن با مرورگر، ابزارهای فعال و نحوه مدیریت دادهها را سفارشیسازی کنند.
سرور را با ارسال پرچمهای خط فرمان در آرایه args فایل پیکربندی کلاینت Model Context Protocol (MCP) پیکربندی کنید. این فایل معمولاً config.json است.
برای مثال، برای اجرای کروم در حالت بدون سر (headless mode) و استفاده از کانال Canary، از پیکربندی زیر استفاده کنید:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"-y",
"chrome-devtools-mcp@latest",
"--headless",
"--channel=canary"
]
}
}
}
سناریوهای پیکربندی رایج
سناریوهای زیر روشهای رایج پیکربندی Chrome DevTools برای عاملها را شرح میدهند.
در حالت بدون سر اجرا کنید
برای انجام وظایف پسزمینه بدون نمایش پنجره مرورگر، کروم را در حالت headless (بدون رابط کاربری) اجرا کنید. پرچم --headless را به آرگومانهای سرور خود اضافه کنید.
اتصال به یک جلسه مرورگر موجود
به طور پیشفرض، DevTools برای agentها یک نمونه جدید Chrome را شروع میکند. با این حال، میتوانید agent خود را به یک session مرورگر موجود متصل کنید. این در صورتی مفید است که agent شما نیاز به بررسی یک مشکل در session ای که قبلاً شروع کردهاید (مثلاً اگر قبلاً وارد سیستم شدهاید) داشته باشد.
شما میتوانید به دو روش به یک جلسه موجود متصل شوید:
اتصال خودکار (کروم ۱۴۴+)
اگر از پرچم --autoConnect استفاده کنید، سرور MCP به طور خودکار به یک نمونه فعال Chrome متصل میشود.
- در مرورگر کروم خود، به
chrome://inspect/#remote-debuggingبروید و Remote Debugging را فعال کنید. -
--autoConnectبه پیکربندی MCP خود اضافه کنید:json "args": ["chrome-devtools-mcp@latest", "--autoConnect"] - وقتی عامل سعی در اتصال دارد، کروم پنجرهای را نشان میدهد که از شما اجازه میخواهد. روی «اجازه دادن» کلیک کنید.
اتصال دستی
اگر نمیتوانید از --autoConnect استفاده کنید (مثلاً در یک محیط سندباکس)، میتوانید کروم را به صورت دستی با یک پورت اشکالزدایی راهاندازی کنید و با استفاده از --browser-url متصل شوید.
- کروم را از ترمینال با فعال بودن اشکالزدایی از راه دور و یک دایرکتوری دادههای کاربر سفارشی اجرا کنید.
- macOS :
shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable - ویندوز :
shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable - لینوکس :
shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
- macOS :
- عامل خود را برای اتصال به این پورت پیکربندی کنید:
json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]
مرجع گزینههای پیکربندی
بخشهای زیر فهرستی از پرچمهای پیکربندی موجود را نشان میدهند. برای جدیدترین گزینهها و بهروزرسانیها، به مخزن GitHub مربوط به Chrome DevTools MCP مراجعه کنید.
گزینههای اتصال
از این گزینهها برای پیکربندی نحوه اتصال سرور به کروم استفاده کنید.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--autoConnect --یا --auto-connect | بولی | false | به طور خودکار به یک نمونه Chrome که به صورت محلی اجرا میشود (۱۴۴+) متصل میشود. نیاز به فعال کردن اشکالزدایی از راه دور با استفاده از chrome://inspect/#remote-debugging . |
--browserUrl یا --browser-url-u | رشته | false | به یک نمونه کروم در حال اجرا و قابل اشکالزدایی متصل شوید (برای مثال، http://127.0.0.1:9222 ). |
--wsEndpoint یا --ws-endpoint-w | رشته | false | نقطه پایانی WebSocket برای اتصال به یک نمونه Chrome در حال اجرا (برای مثال، ws://127.0.0.1:9222/devtools/browser/<id> ). جایگزینی برای --browserUrl . |
--wsHeaders یا --ws-headers | رشته | false | هدرهای سفارشی برای اتصال WebSocket در قالب JSON (برای مثال، '{"Authorization":"Bearer token"}' ). فقط با --wsEndpoint کار میکند. |
گزینههای راهاندازی مرورگر
این گزینهها زمانی اعمال میشوند که سرور MCP، کروم را اجرا کند.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--headless | بولی | false | کروم را در حالت بدون رابط کاربری (headless mode) اجرا میکند. |
--channel | رشته | stable | کانال کروم مورد استفاده را مشخص میکند. انتخابها: canary ، dev ، beta و stable . |
--executablePath یا --executable-path-e | رشته | false | مسیر به یک فایل اجرایی سفارشی کروم. |
--userDataDir یا --user-data-dir | رشته | توضیحات را ببینید | مسیر به دایرکتوری دادههای کاربر. پیشفرض $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE است. |
--isolated | بولی | false | یک دایرکتوری موقت از دادههای کاربر ایجاد میکند که با بسته شدن مرورگر، بهطور خودکار پاک میشود. |
--viewport | رشته | false | اندازه اولیه نمای دید (برای مثال، 1280x720 ). در حالت بدون سر، حداکثر اندازه 3840x2160 است. |
--proxyServer یا --proxy-server | رشته | false | پیکربندی سرور پروکسی به Chrome منتقل شد. |
--chromeArg یا --chrome-arg | آرایه | false | آرگومانهای اضافی برای ارسال به کروم. |
--ignoreDefaultChromeArg یا --ignore-default-chrome-arg | آرایه | false | آرگومانهای پیشفرض را برای کروم به طور صریح غیرفعال کنید. |
گزینههای امنیتی و حریم خصوصی
از این گزینهها برای مدیریت تنظیمات امنیتی و حریم خصوصی دادهها استفاده کنید.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--acceptInsecureCerts یا --accept-insecure-certs | بولی | false | خطاهای مربوط به گواهیهای خودامضا و منقضیشده را نادیده میگیرد. با احتیاط استفاده شود. |
--blockedUrlPattern --blocked-url-pattern | آرایه | false | با مسدود کردن الگوهای URL مشخص شده (با استفاده از URLPattern )، دسترسی به شبکه را محدود میکند. پیمایشها و زیرمنابع را مسدود میکند. |
--allowedUrlPattern یا --allowed-url-pattern | آرایه | false | دسترسی به شبکه را با اجازه دادن به الگوهای URL مشخص شده محدود میکند. به Chrome 149+ نیاز دارد. |
--redactNetworkHeaders یا --redact-network-headers | بولی | false | هدرهای حساس شبکه را قبل از بازگرداندن آنها به کلاینت، ویرایش میکند. |
--usageStatistics یا --usage-statistics | بولی | true | جمعآوری آمار استفاده را برای بهبود ابزار فعال میکند. همچنین میتوان آن را با استفاده از متغیرهای محیطی CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS یا CI غیرفعال کرد. |
--performanceCrux یا --performance-crux | بولی | true | URLها را از ردیابیهای عملکرد به API گوگل CrUX ارسال میکند تا دادههای تجربه کاربر واقعی را دریافت کند. |
دسته بندی ویژگی ها
شما میتوانید با استفاده از این پرچمها، گروههایی از ابزارها را فعال یا غیرفعال کنید.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--categoryEmulation یا --category-emulation | بولی | true | ابزارهای مرتبط با شبیهسازی را فعال میکند. |
--categoryNetwork یا --category-network | بولی | true | ابزارهای مرتبط با شبکه را فعال میکند. |
--categoryPerformance یا --category-performance | بولی | true | ابزارهای مرتبط با عملکرد را فعال میکند. |
--categoryExtensions یا --category-extensions | بولی | false | ابزارهای مربوط به افزونهها را فعال میکند. فقط با اتصال لوله پشتیبانی میشود. |
--categoryExperimentalThirdParty یا --category-experimental-third-party | بولی | false | ابزارهای توسعهدهنده شخص ثالث را که توسط صفحه بازرسیشده در معرض دید قرار میگیرند، فعال میکند. |
--categoryExperimentalWebmcp یا --category-experimental-webmcp | بولی | false | فعال کردن ابزارهای اشکالزدایی WebMCP. به کروم ۱۴۹+ با ویژگیهای فعال WebMCP نیاز دارد. |
--memoryDebugging --memory-debugging | بولی | false | ابزارهای اشکالزدایی حافظه را فعال میکند. |
گزینههای اسکرینشات
از این گزینهها برای سفارشیسازی نحوهی گرفتن اسکرینشات توسط اپراتور استفاده کنید.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--screenshotFormat یا --screenshot-format | رشته | false | فرمت خروجی پیشفرض ( png ) را لغو میکند. گزینههای موجود: jpeg ، png و webp . فرمتهای jpeg و webp کوچکتر هستند که به کاهش اندازه متن در مکالمات هوش مصنوعی کمک میکند. |
کیفیت --screenshotQuality یا --screenshot-quality | شماره | false | کیفیت فشردهسازی (0-100) را برای jpeg و webp لغو میکند. |
--screenshotMaxWidth یا --screenshot-max-width | شماره | false | حداکثر عرض بر حسب پیکسل. اسکرینشاتهای بزرگتر کوچکتر میشوند. |
--screenshotMaxHeight یا --screenshot-max-height | شماره | false | حداکثر ارتفاع بر حسب پیکسل. اسکرینشاتهای بزرگتر کوچکتر میشوند. |
گزینههای آزمایشی
از این گزینهها برای فعال کردن ویژگیهای آزمایشی که در دست توسعه هستند استفاده کنید.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--experimentalPageIdRouting یا --experimental-page-id-routing | بولی | false | شناسه pageId در ابزارهای محدود به صفحه (page-scope) برای مسیریابی درخواستها در جلسات عامل همزمان (agent sessions) در معرض نمایش قرار میدهد. |
--experimentalDevtools یا --experimental-devtools | بولی | false | خودکارسازی را روی اهداف DevTools فعال میکند. |
--experimentalVision یا --experimental-vision | بولی | false | ابزارهای مبتنی بر مختصات (مثلاً click_at ) را فعال میکند. معمولاً به یک مدل کامپیوتری نیاز دارد که بتواند با نگاه کردن به اسکرینشاتها، مختصات دقیقی تولید کند. |
--experimentalStructuredContent یا --experimental-structured-content | بولی | false | محتوای قالببندیشدهی ساختاریافته را خروجی میدهد. |
--experimentalIncludeAllPages یا --experimental-include-all-pages | بولی | false | شامل انواع صفحات (برای مثال، صفحات وب و صفحات پسزمینه) میشود. |
--experimentalScreencast یا --experimental-screencast | بولی | false | ابزارهای ضبط صفحه نمایش را نمایش میدهد ( ffmpeg در PATH نیاز دارد). |
--experimentalFfmpegPath یا --experimental-ffmpeg-path | رشته | false | مسیر فایل اجرایی ffmpeg . |
گزینههای دیگر
از این گزینهها برای پیکربندی ثبت وقایع یا فعال کردن مجموعهای ساده از ابزارها استفاده کنید.
| پرچم | نوع | پیشفرض | توضیحات |
|---|---|---|---|
--slim | بولی | false | مجموعهای کوچک از سه ابزار (ناوبری، اجرای اسکریپت و اسکرینشات) را در اختیار شما قرار میدهد. برای کارهای اولیه مرورگر مفید است. |
--logFile یا --log-file | رشته | false | مسیر فایلی که گزارشهای اشکالزدایی در آن نوشته میشود. |
متغیرهای محیطی
همچنین میتوانید از متغیرهای محیطی زیر برای پیکربندی سرور استفاده کنید:
-
CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: در صورت تنظیم، جمعآوری آمار استفاده را غیرفعال میکند (معادل--no-usage-statistics). -
CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: اگر تنظیم شود، بررسیهای دورهای برای بهروزرسانیها را غیرفعال میکند. -
CI: در صورت تنظیم، جمعآوری آمار استفاده را غیرفعال میکند. -
DEBUG: برای فعال کردن ثبت وقایع اشکالزدایی مفصل (که همراه با--logFileکار میکند)، روی*تنظیم کنید.