> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# إعداد خادم ClickHouse MCP
> وصّل خادم ClickHouse MCP بـ Claude Code أو Claude Desktop أو Codex أو ChatGPT أو Cursor أو Windsurf.
يتيح [خادم ClickHouse MCP](https://github.com/ClickHouse/mcp-clickhouse) للمساعدات المتوافقة المدعومة بالذكاء الاصطناعي استكشاف قواعد البيانات وفحص الجداول وتشغيل استعلامات SQL على ClickHouse.
يشرح هذا الدليل كيفية تهيئة خادم `stdio` محلي باستخدام `uv` وربطه بأحد عملاء MCP الرئيسيين.
يسمح الخادم، افتراضيًا، بتنفيذ استعلامات القراءة فقط.
استخدم مستخدم ClickHouse مخصصًا لا يملك سوى الأذونات التي يحتاج إليها المساعد، ولا تستخدم مستخدم `default` أو مستخدمًا إداريًا.
يوضح الشرح التالي الإعداد باستخدام Claude Desktop.
وتنطبق تفاصيل اتصال ClickHouse نفسها على العملاء الآخرين المشمولين في هذا الدليل.
## المتطلبات الأساسية
قبل البدء:
1. [ثبّت `uv`](https://docs.astral.sh/uv/getting-started/installation/).
2. ثبّت عميل MCP الذي تريد استخدامه.
3. اجمع اسم المضيف واسم المستخدم وكلمة المرور الخاصة بخدمة ClickHouse لديك.
تستخدم الأمثلة أدناه قيم العناصر النائبة التالية:
| متغير البيئة | القيمة |
| --------------------- | -------------------------- |
| `CLICKHOUSE_HOST` | `your-clickhouse-host` |
| `CLICKHOUSE_USER` | `your-clickhouse-user` |
| `CLICKHOUSE_PASSWORD` | `your-clickhouse-password` |
استبدلها بتفاصيل الاتصال لديك.
بالنسبة إلى خدمة ClickHouse Cloud، يستخدم الخادم بروتوكول HTTPS على المنفذ `8443` افتراضيًا.
بالنسبة إلى خدمة مُدارة ذاتيًا تستخدم بروتوكول HTTP غير المشفّر، اضبط أيضًا `CLICKHOUSE_SECURE=false`، وإذا لزم الأمر، اضبط `CLICKHOUSE_PORT=8123`.
## تهيئة عميل MCP الخاص بك
نفّذ الأمر التالي في الطرفية:
```bash theme={null}
claude mcp add \
--transport stdio \
--env CLICKHOUSE_HOST=your-clickhouse-host \
--env CLICKHOUSE_USER=your-clickhouse-user \
--env CLICKHOUSE_PASSWORD=your-clickhouse-password \
--scope user \
mcp-clickhouse -- \
uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse
```
شغّل `claude mcp list` للتحقق من الاتصال، أو أدخل `/mcp` في Claude Code لاستعراض الخادم وأدواته.
في Claude Desktop، افتح **الإعدادات**، ثم اختر **Developer** و**Edit config**.
أضف الخادم التالي إلى `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "your-clickhouse-host",
"CLICKHOUSE_USER": "your-clickhouse-user",
"CLICKHOUSE_PASSWORD": "your-clickhouse-password"
}
}
}
}
```
احفظ الملف ثم أعد تشغيل Claude Desktop.
افتح **Connectors** من مربع كتابة الدردشة للتأكد من توفّر `mcp-clickhouse`.
أضف الخادم باستخدام واجهة سطر الأوامر لـ Codex:
```bash theme={null}
codex mcp add mcp-clickhouse \
--env CLICKHOUSE_HOST=your-clickhouse-host \
--env CLICKHOUSE_USER=your-clickhouse-user \
--env CLICKHOUSE_PASSWORD=your-clickhouse-password \
-- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse
```
شغّل `codex mcp list` للتحقق من الاتصال، أو أدخل `/mcp` في واجهة Codex الطرفية.
تستخدم واجهة سطر الأوامر لـ Codex وامتداد Codex لـ IDE وتطبيق ChatGPT لسطح المكتب تهيئة MCP نفسها في `~/.codex/config.toml`.
يهيّئ تطبيق ChatGPT لسطح المكتب خوادم MCP محلية لمضيف Codex الخاص به.
وتتم مشاركة هذه التهيئة مع واجهة سطر الأوامر Codex وامتداد Codex لبيئة التطوير المتكاملة.
في تطبيق ChatGPT لسطح المكتب:
1. افتح **الإعدادات**، ثم اختر **خوادم MCP**.
2. اختر **إضافة خادم** ثم اختر **STDIO**.
3. أدخل `mcp-clickhouse` اسمًا و`uv` أمرًا.
4. أضف `run` و`--with` و`mcp-clickhouse` و`--python` و`3.10` و`mcp-clickhouse` كوسيطات، بهذا الترتيب.
5. أضف `CLICKHOUSE_HOST` و`CLICKHOUSE_USER` و`CLICKHOUSE_PASSWORD` مع تفاصيل الاتصال الخاصة بك.
6. احفظ الخادم وأعد تشغيل التطبيق.
بعد إعادة تشغيل التطبيق، افتح Codex وأدخل `/mcp` في مربع الإنشاء للتحقق من الخادم المتصل.
تهيّئ هذه الخطوات خادم `stdio` محليًا لـ Codex في تطبيق ChatGPT لسطح المكتب.
أما ChatGPT على الويب، فيستخدم أدوات MCP بعيدة توفّرها المكونات الإضافية.
لاستخدام أدوات ClickHouse في ChatGPT على الويب، راجع [خادم MCP البعيد في ClickHouse Cloud](/ar/products/cloud/features/ai-ml/remote-mcp).
أضف الخادم التالي إلى ملف `.cursor/mcp.json` الخاص بالمشروع الحالي، أو إلى إعدادات Cursor MCP العامة لديك:
```json theme={null}
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "your-clickhouse-host",
"CLICKHOUSE_USER": "your-clickhouse-user",
"CLICKHOUSE_PASSWORD": "your-clickhouse-password"
}
}
}
}
```
أعد تشغيل Cursor، ثم افتح إعدادات MCP للتأكد من تفعيل الخادم.
أضِف الخادم التالي إلى `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "your-clickhouse-host",
"CLICKHOUSE_USER": "your-clickhouse-user",
"CLICKHOUSE_PASSWORD": "your-clickhouse-password"
}
}
}
}
```
أعِد تشغيل Windsurf، ثم افتح إعدادات MCP للتأكد من أن الخادم مفعّل.
## تحقّق من الاتصال
بعد أن يُبلغ العميل بأن `mcp-clickhouse` متصل، اطلب منه:
```text theme={null}
List the databases available in ClickHouse, then show me the tables in one of them.
```
قد يطلب منك العميل اعتماد استدعاءات الأدوات الأولى.
راجع كل طلب قبل منح صلاحية الوصول.
## استكشاف الأخطاء وإصلاحها
إذا أبلغ العميل بتعذّر العثور على `uv`، فاستبدل `uv` في الأمر أو الإعداد بمساره المطلق.
شغّل `which uv` على macOS أو Linux، أو `where uv` على Windows، للعثور على هذا المسار.
للاطلاع على إعدادات اتصال إضافية ودعم chDB الاختياري ونقل HTTP والمصادقة، راجع ملف README الخاص بـ [`mcp-clickhouse`](https://github.com/ClickHouse/mcp-clickhouse).