MCP Toolbox for Databases

لماذا تستخدمه

الميزات الأساسية

ثنائي واحد لمحركات متعددة: Postgres وMySQL وBigQuery وSpanner وAlloyDB وCloud SQL وSQLite وMSSQL وRedis وCouchbase وDgraph وNeo4j
ملف tools.yaml تعريفي — كل أداة عبارة عن جملة مُسمَّاة ذات معاملات، لا بوابة SQL مفتوحة
إعدادات جاهزة (--prebuilt postgres) للاستخدام الفوري دون أي إعداد
تجميع الاتصالات والمصادقة (IAM وOAuth ومفتاح API) مُدارَة مركزياً لا في prompt
نقل Stdio أو HTTP/SSE — يعمل مع Claude Desktop وCursor وCodex والـ IDEs والوكلاء المخصصين
قواعد تفويض على مستوى كل أداة — قيّد من يمكنه استدعاء العمليات التدميرية

عرض مباشر

كيف يبدو في الممارسة

mcp-toolbox-databases.replay ▶ جاهز

0/0

التثبيت

اختر العميل

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

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

افتح Claude Desktop → Settings → Developer → Edit Config. أعد التشغيل بعد الحفظ.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

يستخدم Cursor نفس مخطط mcpServers مثل Claude Desktop. إعدادات المشروع أولى من الإعدادات العامة.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

انقر على أيقونة MCP Servers في شريط Cline الجانبي، ثم "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

نفس الصيغة مثل Claude Desktop. أعد تشغيل Windsurf لتطبيق التغييرات.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

يستخدم Continue مصفوفة من كائنات الخادم بدلاً من خريطة.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

أضف إلى context_servers. يعيد Zed التحميل تلقائيًا عند الحفظ.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

أمر من سطر واحد. تحقق باستخدام claude mcp list. احذف باستخدام claude mcp remove.

حالات الاستخدام

استخدامات عملية: MCP Toolbox for Databases

كيف تمنح Claude صلاحية قراءة فقط آمنة لقاعدة Postgres في الإنتاج

👤 مهندسو الواجهة الخلفية والبيانات الراغبون في تحليل LLM دون خطر تسريب البيانات ⏱ ~25 min intermediate

متى تستخدمه: تريد أن يجيب Claude على أسئلة عن قاعدة بيانات حقيقية دون أداة execute_sql عامة قادرة على تنفيذ DROP TABLE.

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

Postgres قابل للوصول عبر libpq URL — استخدم دوراً بصلاحية قراءة فقط؛ لا تستخدم مستخدم التطبيق الذي لديه صلاحية كتابة أبداً
Docker أو Go مُثبَّت — يُشحن Toolbox كثنائي واحد؛ صورة Docker هي الأسهل

الخطوات

تشغيل Toolbox مع ملف تعريف postgres الجاهز

Start mcp-toolbox in stdio mode using --prebuilt postgres and POSTGRES_URL pointing at the read replica.✓ تم النسخ

→ يسجّل Toolbox tools registered: list_tables, describe_table, execute_sql_readonly
ربطه بـ Claude Desktop

Add the toolbox docker config to claude_desktop_config.json under mcpServers, then restart Claude.✓ تم النسخ

→ يُدرج /mcp أدوات toolbox دون أخطاء
طرح سؤال حقيقي

Toolbox: list tables. Then for orders, what's the median order value in the last 7 days? Show me the exact SQL you ran.✓ تم النسخ

→ يستدعي Claude: list_tables ثم describe_table ثم execute_sql_readonly بجملة SELECT فقط (لا UPDATE ولا DELETE)

النتيجة: تحليلات للقراءة فقط على بيانات حقيقية دون خطر تعديلها، مع سجل تدقيق لكل استعلام.

المزالق

الإشارة إلى المستخدم القابل للكتابة — سيستدعي Claude في نهاية المطاف أداة تغيير — استخدم دائماً دوراً بصلاحية GRANT SELECT فقط؛ تحقق باستخدام \du في psql
استنفاد pool الاتصالات عند الاستدعاءات المتوازية للوكيل — اضبط pool.max_open_conns في tools.yaml؛ القيمة الافتراضية محافظة

اجمعها مع: filesystem · github

تعريف أداة محلل مكتوبة يدوياً مع التحقق من المعاملات

👤 الفرق التي لا تريد SQL خاماً، بل استعلامات معتمدة فقط ⏱ ~20 min intermediate

متى تستخدمه: تريد أن يجيب Claude على سؤال 'أفضل 10 عملاء هذا الشهر' دون أن يخترع صلات بنفسه.

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

ملف tools.yaml — أنشئه في ~/.mcp-toolbox/tools.yaml

الخطوات

كتابة أداة ذات معاملات

Add a tool top_customers to tools.yaml: parameter since: date, statement SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ تم النسخ

→ يُعيد Toolbox التحميل ويعرض top_customers فقط — لا execute_sql_readonly
الاستدعاء من Claude

Use top_customers since=2026-04-01 and explain the result.✓ تم النسخ

→ استدعاء أداة واحد بمعامل تاريخ مُتحقَّق منه، ونتيجة منسقة

النتيجة: واجهة محللة مقفلة — لا يمكن لـ Claude تشغيل أي شيء لم تُصرِّح به.

المزالق

نسيان إزالة أداة execute_sql الجاهزة — احذف --prebuilt؛ حمِّل ملف tools.yaml الخاص بك فقط

استكشاف مجموعات بيانات BigQuery دون كتابة SQL

👤 المحللون على Google Cloud ⏱ ~20 min intermediate

متى تستخدمه: لديك مشروع BigQuery وتريد من Claude الإجابة على أسئلة عبره مع ضوابط للتكلفة.

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

مشروع GCP + مجموعة بيانات — شغّل gcloud auth application-default login حتى يلتقط Toolbox بيانات الاعتماد

الخطوات

تشغيل Toolbox مع --prebuilt bigquery

Run toolbox --prebuilt bigquery with PROJECT=my-proj.✓ تم النسخ

→ الأدوات bq_list_datasets وbq_dry_run وbq_query مُسجَّلة
التشغيل التجريبي دائماً أولاً

Before running any query, call bq_dry_run to estimate the bytes scanned. If > 1GB, ask me before running.✓ تم النسخ

→ تقدير التكلفة يظهر قبل الاستعلام المُدفوع

النتيجة: إجابات BigQuery مع ضوابط للتكلفة — لا مفاجآت باستعلام بـ 200 دولار.

المزالق

عدم تطابق الموقع الافتراضي (US مقابل EU) — اضبط متغير البيئة BIGQUERY_LOCATION

الاستعلام من قواعد بيانات متعددة في جلسة Claude واحدة

👤 المهندسون الذين يصحِّحون مشكلات متعددة المتاجر ⏱ ~30 min advanced

متى تستخدمه: بيانات الطلبات في Postgres والأحداث في BigQuery والذاكرة المخبأة في Redis — تحتاج إلى ربطها معاً.

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

ملف tools.yaml بمصادر متعددة — عرِّف كل مصدر تحت sources: وأضف علامة المصدر للأدوات

الخطوات

توصيل المصادر الثلاثة

Add postgres-prod, bq-events, redis-cache as sources in tools.yaml. Add 1–2 tools per source.✓ تم النسخ

→ يبدأ Toolbox ويُشير إلى جميع المصادر بأنها في حالة سليمة
طرح سؤال متعدد المتاجر

For order 12345: pull the row from Postgres, the event timeline from BigQuery, and the current cache state from Redis. Reconcile.✓ تم النسخ

→ ثلاثة استدعاءات أدوات موزعة، إجابة واحدة متماسكة

النتيجة: تصحيح أخطاء متعددة المتاجر دون ثلاث أدوات منفصلة أو جلسات SSH.

المزالق

فشل فحص صحة المصدر بصمت — شغّل toolbox validate tools.yaml قبل البدء

اجمعها مع: filesystem

التركيبات

اجمعها مع خوادم MCP أخرى لتحقيق نتائج x10

mcp-toolbox-databases + filesystem

سحب نتيجة استعلام وحفظها في ملف CSV في مساحة عملك

Toolbox: top 100 orders this week. Filesystem: save as /tmp/orders.csv.✓ تم النسخ

mcp-toolbox-databases + github

فتح طلب سحب PR بترحيل SQL بعد أن يقترح Claude تغيير المخطط

Toolbox: describe the orders table. GitHub: open a PR adding an index on customer_id.✓ تم النسخ

الأدوات

ما يوفره هذا الـ MCP

الأداة	المدخلات	متى تستدعيها	التكلفة
list_tables	schema?: str	خطوة الاستكشاف الأولى	1 query
describe_table	table: str	قبل كتابة SQL على جدول مجهول	1 query
execute_sql_readonly	sql: str	التحليل الحر على replica القراءة فقط	1 query
bq_dry_run	sql: str	BigQuery: دائماً قبل bq_query	free (dry run)
bq_query	sql: str	بعد أن يُظهر الـ dry run تكلفة مقبولة	billable per bytes scanned
<your-custom-tool>	depends on tools.yaml	أي شيء عرَّفته في tools.yaml	1 query

التكلفة والحدود

تكلفة التشغيل

حصة API: لا شيء — مقيَّد بسعة الاتصالات في قاعدة بياناتك
الرموز لكل استدعاء: 100–5000 حسب حجم النتيجة
التكلفة المالية: مجاني مفتوح المصدر؛ يُفوتر قاعدة البيانات / السحابة بشكل طبيعي
نصيحة: قيِّد صفوف النتائج في tools.yaml (مثلاً LIMIT 200)؛ لـ BigQuery مرِّر دائماً عبر bq_dry_run أولاً

الأمان

الصلاحيات والأسرار ونطاق الأثر

الحد الأدنى من الصلاحيات: read-only DB role

تخزين بيانات الاعتماد: متغيرات البيئة أو Google ADC؛ لا يحتفظ Toolbox ببيانات الاعتماد

نقل البيانات الخارجي: اتصال مباشر بقاعدة البيانات — لا عبور لطرف ثالث. Toolbox محلي فقط.

لا تمنح أبدًا: DBA DROP/TRUNCATE on prod

ضع دائماً replica قراءة فقط مع دور قراءة فقط أمام الإنتاج؛ لا تستخدم مستخدم التطبيق القابل للكتابة أبداً

استكشاف الأخطاء

الأخطاء الشائعة وحلولها

connection refused / pool exhausted

أَزِد pool.max_open_conns في tools.yaml؛ تحقق من حد اتصالات قاعدة البيانات

تحقق: psql, run SELECT count(*) FROM pg_stat_activity

tool not found

إذا كنت تستخدم --prebuilt، اسم الأداة مثلاً pg_list_tables؛ تحقق باستخدام toolbox list-tools

BigQuery 403 access denied

شغّل gcloud auth application-default login ومنح roles/bigquery.dataViewer

تحقق: bq ls

Spanner Cloud SDK errors

اضبط GOOGLE_APPLICATION_CREDENTIALS على ملف JSON لحساب خدمة

البدائل