AI导哈

MariaDB数据库管理服务

MCP MariaDB Server提供了一个模型上下文协议（MCP）接口，用于管理和查询MariaDB数据库，支持标准SQL操作和基于向量/嵌入的高级搜索，适用于AI助手驱动的数据工作流。

  • by Diae-Louali
  • 本地部署
  • 更新于
在 GitHub 查看 diae-louali/mcp

使用说明

MCP MariaDB服务器

MCP MariaDB服务器提供了一个模型上下文协议（MCP）接口，用于管理和查询MariaDB数据库，支持标准SQL操作和高级基于向量/嵌入的搜索。它专为与人工智能助手一起使用而设计，能够将人工智能驱动的数据工作流程与关系数据库和向量数据库无缝集成。

目录

概述

MCP MariaDB Server提供了一组工具，用于通过标准化协议与MariaDB数据库和矢量存储进行交互。它支持：

  • 列出数据库和表
  • 正在检索表架构
  • 执行安全的只读SQL查询
  • 为基于嵌入的搜索创建和管理矢量存储
  • 与嵌入提供商（目前为OpenAI、Gemini和HuggingFace）集成（可选）

核心组件

  • 服务器.py：主MCP服务器逻辑和工具定义。
  • config.py：从环境加载配置 .env 文件夹。
  • 嵌入.py：处理嵌入服务集成（OpenAI）。
  • 测试/：手动和自动测试文档和脚本。

可用工具

标准数据库工具

  • 列表_数据库

    • 列出所有可访问的数据库。
    • 参数： 无

  • list_tables

    • 列出指定数据库中的所有表。
    • 参数： database_name （字符串，必填）

  • get_table_schema

    • 检索表的架构（列、类型、键等）。
    • 参数： database_name （字符串，必填）， table_name （字符串，必填）

  • get_table_schema_with_relations

    • 检索表的具有外键关系的架构。
    • 参数： database_name （字符串，必填）， table_name （字符串，必填）

  • execute_sql

    • 执行只读SQL查询(SELECT, SHOW, DESCRIBE).
    • 参数： sql_query （字符串，必填）， database_name （字符串，可选）， parameters （列表，可选）
    • 注意：如果满足以下条件，则强制只读模式 MCP_READ_ONLY 已启用。

  • create_database

    • 如果不存在，则创建新数据库。
    • 参数： database_name （字符串，必填）

矢量存储和嵌入工具（可选）

备注：这些工具仅在以下情况下可用 EMBEDDING_PROVIDER 已配置。如果没有设置嵌入提供程序，这些工具将被禁用。

  • create_vector_store

    • 为嵌入创建新的向量存储（表）。
    • 参数： database_name, vector_store_name, model_name （可选）， distance_function （可选，默认值：余弦）

  • delete_vector_store

    • 删除向量存储（表）。
    • 参数： database_name, vector_store_name

  • list_vector_store

    • 列出数据库中的所有矢量存储。
    • 参数： database_name

  • insert_docs_vector_store

    • 批量将文档（和可选元数据）插入到向量存储中。
    • 参数： database_name, vector_store_name, documents （字符串列表）， metadata （可选字典列表）

  • search_vector_store

    • 使用嵌入对类似文档执行语义搜索。
    • 参数： database_name, vector_store_name, user_query （字符串）， k （可选，默认值：7）

嵌入和矢量存储

概述

MCP MariaDB服务器提供 可选的 嵌入和矢量存储功能。这些功能可以通过配置嵌入提供程序来启用，如果您只需要标准的数据库操作，则可以完全禁用。

支持的提供商

  • OpenAI
  • 双子座
  • Huggingface的开放模型

配置

  • EMBEDDING_PROVIDER：设置为 openai, gemini, huggingface，或保持未设置以禁用
  • OPENAI_API_KEY：如果使用OpenAI嵌入，则需要
  • GEMINI_API_KEY：如果使用Gemini嵌入，则需要
  • HF_MODEL：如果使用HuggingFace嵌入（例如“intfloat/多语言e5-large-instructure”或“BAAI/bge-m3”），则需要

模型选择

  • 默认和允许的模型可以在代码中配置(DEFAULT_OPENAI_MODEL, ALLOWED_OPENAI_MODELS)
  • 可以根据请求选择模型，也可以默认为配置的模型

矢量存储架构

矢量存储表有以下列：

  • id：自动递增主键
  • document：文件文本
  • embedding：矢量类型（索引用于相似性搜索）
  • metadata：JSON（可选元数据）

配置和环境变量

所有配置都是通过环境变量（通常在 .env 文件）：

变量 描述 必填 默认
DB_HOST MariaDB主机地址 是 localhost
DB_PORT MariaDB端口 否 3306
DB_USER MariaDB用户名 是
DB_PASSWORD MariaDB密码 是
DB_NAME 默认数据库（可选；可按查询设置） 否
MCP_READ_ONLY 强制只读SQL模式(true/false) 没有 true
MCP_MAX_POOL_SIZE 最大DB连接池大小 否 10
EMBEDDING_PROVIDER 嵌入提供者(openai/gemini/huggingface) 没有 None（残疾人）
OPENAI_API_KEY OpenAI嵌入的API密钥 是（如果EMBEDDING_PROVIDER=OpenAI）
GEMINI_API_KEY Gemini嵌入的API密钥 是（如果EMBEDDING_PROVIDER=Gemini）
HF_MODEL 从Huggingface打开模型 是（如果EMBEDDING_PROVIDER=Huggingface）

示例 .env 文件

使用嵌入支持（OpenAI）：

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database

MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
HF_MODEL="BAAI/bge-m3"

没有嵌入支持：

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database
MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

安装和设置

需求

  • Python 3.11 （参见 .python-version)
  • 紫外线 （依赖关系管理器； 安装说明)
  • MariaDB服务器（本地或远程）

步骤

  1. 克隆存储库
  2. 安装 uv （如果还没有）：
    pip install uv
  3. 安装依赖项
    uv pip compile pyproject.toml -o uv.lock

    uv pip sync uv.lock
  4. 创建 .env 在项目根目录中（请参见 配置)
  5. 运行服务器
    python server.py
    如果需要，调整入口点（例如。， main.py)

使用示例

标准SQL查询

{
  "tool": "execute_sql",
  "parameters": {
    "database_name": "test_db",
    "sql_query": "SELECT * FROM users WHERE id = %s",
    "parameters": [123]
  }
}

创建矢量存储

{
  "tool": "create_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "model_name": "text-embedding-3-small",
    "distance_function": "cosine"
  }
}

将文档插入矢量存储

{
  "tool": "insert_docs_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "documents": ["Sample text 1", "Sample text 2"],
    "metadata": [{"source": "doc1"}, {"source": "doc2"}]
  }
}

语义搜索

{
  "tool": "search_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "user_query": "What is the capital of France?",
    "k": 5
  }
}

集成-克劳德桌面/光标/Windsurf/VSCode

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mariadb-mcp-server/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

或 如果已在运行MCP服务器

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/sse",
      "type": "sse"
    }
  }
}

日志记录

  • 日志被写入 logs/mcp_server.log 默认情况下。
  • 日志消息包括工具调用、配置问题、嵌入错误和客户端请求。
  • 日志级别和输出可以在代码中调整（参见 config.py 以及记录器设置）。

测试

  • 测试位于 src/tests/ 目录。
  • 看 src/tests/README.md 查看概述。
  • 测试涵盖了标准SQL和向量/嵌入工具操作。

相关 MCP