关键词

MariaDB数据库访问向量数据库语义搜索LLM工具

项目简介

MariaDB MCP 服务端是一个基于Model Context Protocol (MCP) 的后端应用，旨在帮助大型语言模型（LLM）客户端与MariaDB数据库进行无缝交互。它以标准化的方式提供数据库的上下文信息和操作能力，包括执行SQL查询、管理数据库及表格结构，并可选地支持向量存储和语义搜索功能，从而赋能AI助理进行智能数据处理。

主要功能点

  • 数据库信息查询: 列出所有可访问的数据库及其包含的表格。
  • 表格结构获取: 获取指定表格的详细结构（字段、类型、键、关联关系等）。
  • 安全SQL执行: 执行只读的SQL查询（如SELECT、SHOW、DESCRIBE），支持参数化查询以提高安全性。
  • 数据库创建: 创建新的数据库（如果不存在）。
  • 向量存储管理 (可选): 在MariaDB中创建、删除和列出向量存储（表格），用于存储和管理嵌入数据。
  • 文档嵌入与搜索 (可选): 将文档及其元数据批量插入向量存储，并根据用户查询进行语义搜索，找到最相似的文档。
  • 多模型支持 (可选): 集成OpenAI、Google Gemini或HuggingFace等多种嵌入模型，生成高质量的向量嵌入。
  • 灵活的传输协议: 支持Stdio、SSE (Server-Sent Events) 和HTTP等多种通信方式。

安装步骤

  1. 克隆仓库:

    git clone https://github.com/MariaDB/mcp.git
cd mcp

  2. 安装 'uv' (Python 依赖管理器):

    pip install uv

  3. 安装项目依赖:

    uv pip compile pyproject.toml -o uv.lock
uv pip sync uv.lock

  4. 配置环境变量: 在项目根目录创建 '.env' 文件，并根据您的MariaDB数据库和嵌入服务配置信息进行填写。

    示例 '.env' 文件 (带嵌入支持，推荐):

    DB_HOST=localhost
DB_USER=your_mariadb_user
DB_PASSWORD=your_mariadb_password
DB_PORT=3306
DB_NAME=your_default_database # 可选，连接后可切换
MCP_READ_ONLY=true # 建议设为true以限制AI写入操作
MCP_MAX_POOL_SIZE=10

EMBEDDING_PROVIDER=openai # 或 gemini / huggingface
OPENAI_API_KEY=sk-... # 如果使用OpenAI，请填写您的API密钥
# GEMINI_API_KEY=AI... # 如果使用Gemini，请填写您的API密钥
# HF_MODEL="BAAI/bge-m3" # 如果使用HuggingFace，请填写模型名称
    • 请确保MariaDB服务器已运行，并可通过配置的'DB_HOST'、'DB_PORT'、'DB_USER'、'DB_PASSWORD'访问。
    • 根据选择的'EMBEDDING_PROVIDER'，提供相应的API密钥或模型名称。如不需嵌入功能，可删除'EMBEDDING_PROVIDER'及相关行。

服务器配置 (用于MCP客户端)

MCP客户端（如Claude桌面版、Cursor、Windsurf）需要配置MCP服务器的启动信息。以下是JSON格式的配置示例及参数说明：

1. 使用标准输入/输出 (stdio) 方式: 这种方式适用于客户端直接启动并管理MCP服务器进程。

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/your/mcp-mariadb-server-repo/",  // 替换为您的MCP仓库实际路径
        "run",
        "server.py"
      ],
      "envFile": "path/to/your/mcp-mariadb-server-repo/.env", // 替换为您的.env文件实际路径
      "description": "连接MariaDB数据库，提供SQL查询和向量搜索工具。" // 可选，描述此服务器用途
    }
  }
}
  • 'command': 执行服务器的命令，通常是Python环境的启动器（如'uv'或'python'）。
  • 'args': 启动命令的参数列表。
    • '--directory': 指定项目根目录。
    • 'run': 'uv'的子命令，用于执行Python脚本。
    • 'server.py': 服务器的主脚本文件。
  • 'envFile': 指定包含数据库凭据和API密钥的'.env'文件路径。
  • 'description': 自定义服务器描述，方便客户端识别。

2. 使用SSE (Server-Sent Events) 传输方式: 服务器作为HTTP服务运行，客户端通过HTTP URL连接。 首先，在终端启动服务器：

python server.py --transport sse --host 127.0.0.1 --port 9001

然后，在MCP客户端中配置：

{
  "servers": {
    "mariadb-mcp-server-sse": {
      "url": "http://127.0.0.1:9001/sse", // 替换为您的服务器实际地址和端口
      "type": "sse",
      "description": "通过SSE协议连接MariaDB MCP服务器。"
    }
  }
}
  • 'url': MCP服务器的SSE接口URL。
  • 'type': 传输类型，此处为'sse'。

3. 使用HTTP (Streamable HTTP) 传输方式: 服务器作为HTTP服务运行，客户端通过HTTP URL连接。 首先，在终端启动服务器：

python server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp

然后，在MCP客户端中配置：

{
  "servers": {
    "mariadb-mcp-server-http": {
      "url": "http://127.0.0.1:9001/mcp", // 替换为您的服务器实际地址、端口和路径
      "type": "streamable-http",
      "description": "通过HTTP协议连接MariaDB MCP服务器。"
    }
  }
}
  • 'url': MCP服务器的HTTP接口URL。
  • 'type': 传输类型，此处为'streamable-http'。

基本使用方法 (通过MCP客户端调用工具)

一旦MCP客户端连接成功，LLM就可以通过JSON-RPC调用服务器暴露的工具。

1. 列出所有数据库: 调用工具：'list_databases'，无参数。 例如 (客户端内部调用):

{ "tool": "list_databases", "parameters": {} }

2. 执行一个只读SQL查询: 调用工具：'execute_sql'。 参数：

  • 'database_name': 目标数据库名称 (字符串)
  • 'sql_query': SQL查询语句 (字符串)
  • 'parameters': SQL查询的参数列表 (可选，列表) 例如 (客户端内部调用):
{
  "tool": "execute_sql",
  "parameters": {
    "database_name": "your_database",
    "sql_query": "SELECT id, name FROM users WHERE age > %s",
    "parameters": [30]
  }
}

3. 创建一个向量存储: 调用工具：'create_vector_store' (需要启用嵌入功能)。 参数：

  • 'database_name': 目标数据库名称 (字符串)
  • 'vector_store_name': 向量存储的表格名称 (字符串)
  • 'model_name': 用于生成嵌入的模型名称 (可选，字符串)
  • 'distance_function': 向量距离计算函数，'cosine' 或 'euclidean' (可选，字符串，默认为'cosine') 例如 (客户端内部调用):
{
  "tool": "create_vector_store",
  "parameters": {
    "database_name": "ai_data",
    "vector_store_name": "product_descriptions",
    "model_name": "text-embedding-3-small",
    "distance_function": "cosine"
  }
}

4. 插入文档到向量存储: 调用工具：'insert_docs_vector_store' (需要启用嵌入功能)。 参数：

  • 'database_name': 目标数据库名称 (字符串)
  • 'vector_store_name': 向量存储的表格名称 (字符串)
  • 'documents': 要插入的文档列表 (字符串列表)
  • 'metadata': 与每个文档关联的元数据列表 (可选，字典列表) 例如 (客户端内部调用):
{
  "tool": "insert_docs_vector_store",
  "parameters": {
    "database_name": "ai_data",
    "vector_store_name": "product_descriptions",
    "documents": ["高性能笔记本电脑", "超薄智能手机"],
    "metadata": [{"category": "electronics"}, {"category": "mobile"}]
  }
}

5. 语义搜索向量存储: 调用工具：'search_vector_store' (需要启用嵌入功能)。 参数：

  • 'database_name': 目标数据库名称 (字符串)
  • 'vector_store_name': 向量存储的表格名称 (字符串)
  • 'user_query': 用户的查询语句 (字符串)
  • 'k': 返回最相似文档的数量 (可选，整数，默认为7) 例如 (客户端内部调用):
{
  "tool": "search_vector_store",
  "parameters": {
    "database_name": "ai_data",
    "vector_store_name": "product_descriptions",
    "user_query": "寻找适合出差的轻便设备",
    "k": 3
  }
}

信息

分类

数据库与文件

访问项目