إعداد خادم ClickHouse MCP

يتيح خادم ClickHouse MCP للمساعدات المتوافقة المدعومة بالذكاء الاصطناعي استكشاف قواعد البيانات وفحص الجداول وتشغيل استعلامات SQL على ClickHouse. يشرح هذا الدليل كيفية تهيئة خادم stdio محلي باستخدام uv وربطه بأحد عملاء MCP الرئيسيين.

يسمح الخادم، افتراضيًا، بتنفيذ استعلامات القراءة فقط. استخدم مستخدم ClickHouse مخصصًا لا يملك سوى الأذونات التي يحتاج إليها المساعد، ولا تستخدم مستخدم default أو مستخدمًا إداريًا.

يوضح الشرح التالي الإعداد باستخدام Claude Desktop. وتنطبق تفاصيل اتصال ClickHouse نفسها على العملاء الآخرين المشمولين في هذا الدليل.

المتطلبات الأساسية

قبل البدء:

ثبّت uv.
ثبّت عميل MCP الذي تريد استخدامه.
اجمع اسم المضيف واسم المستخدم وكلمة المرور الخاصة بخدمة 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 الخاص بك

نفّذ الأمر التالي في الطرفية:

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:

{
  "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:

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 لسطح المكتب:

افتح الإعدادات، ثم اختر خوادم MCP.
اختر إضافة خادم ثم اختر STDIO.
أدخل mcp-clickhouse اسمًا وuv أمرًا.
أضف run و--with وmcp-clickhouse و--python و3.10 وmcp-clickhouse كوسيطات، بهذا الترتيب.
أضف CLICKHOUSE_HOST وCLICKHOUSE_USER وCLICKHOUSE_PASSWORD مع تفاصيل الاتصال الخاصة بك.
احفظ الخادم وأعد تشغيل التطبيق.

بعد إعادة تشغيل التطبيق، افتح Codex وأدخل /mcp في مربع الإنشاء للتحقق من الخادم المتصل.

أضف الخادم التالي إلى ملف .cursor/mcp.json الخاص بالمشروع الحالي، أو إلى إعدادات Cursor MCP العامة لديك:

{
  "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:

{
  "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 متصل، اطلب منه:

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.