AI导哈

MariaDB数据库管理服务

MCP MariaDB Server提供标准SQL操作和高级向量搜索功能，支持AI助手集成，适用于关系型数据库和向量数据库的管理与查询。

  • by yangmw7
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 yangmw7/looper-game-chatbot-mcp

使用说明

MCP MariaDB 服务器

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

目录

概述

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

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

核心组件

  • **server.py（服务器文件）**主要的MCP服务器逻辑和工具定义。
  • **config.py（配置文件）**从环境加载配置并 .env 文件。
  • **`embeddings.py` 翻译成中文是“嵌入.py”**负责处理嵌入服务集成（OpenAI）。
  • **测试/**手动和自动化测试文档及脚本。

可用工具

标准数据库工具

  • 列出数据库

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

  • 列出表

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

  • 获取表结构

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

  • 获取带有关系的表模式

    • 检索包含外键关系的表模式。
    • 参数： database_name （字符串，必填）， table_name （字符串，必填）

  • 执行SQL

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

  • 创建数据库

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

向量存储与嵌入工具（可选）

注这些工具仅在以下情况下可用： EMBEDDING_PROVIDER 已配置。如果未设置嵌入式服务提供商，这些工具将被禁用。

  • 创建向量存储

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

  • 删除向量存储

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

  • 列表矢量存储

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

  • 插入文档向量存储

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

  • 搜索向量存储

    • 使用嵌入技术对相似文档执行语义搜索。
    • 参数： 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/multilingual-e5-large-instruct”或“BAAI/bge-m3”），则此为必需项

模型选择

  • 默认模型和允许模型可以在代码中进行配置（DEFAULT_OPENAI_MODEL， ALLOWED_OPENAI_MODELS）
  • 模型可根据请求选择，或默认使用配置的模型

向量存储架构

向量存储表包含以下列：

  • id自增主键
  • document文件正文
  • embedding向量类型（为相似性搜索建立索引）
  • metadataJSON（可选元数据）

配置与环境变量

所有配置均通过环境变量进行（通常在 .env 文件)：

变量 描述 是否必需 默认值
（标题栏） （内容栏） （列名） （另一列名）
DB_PORT 3306 MariaDB 端口 否
DB_USER
MariaDB 用户名 是 DB_PASSWORD
MariaDB 密码 是 DB_NAME
默认数据库（可选；可针对每个查询设置） 否 DB_CHARSET
) 否 MariaDB 默认 MCP_READ_ONLY
MCP_MAX_POOL_SIZE 10 最大数据库连接池大小 否
EMBEDDING_PROVIDER openai 嵌入服务提供商 (gemini/huggingface/None) 否
(残疾) OPENAI_API_KEY
以下是根据您提供的信息翻译的内容： GEMINI_API_KEY
OpenAI嵌入的API密钥 是（如果EMBEDDING_PROVIDER=openai） HF_MODEL

以下是根据您提供的信息翻译后的内容： .env

| Gemini嵌入的API密钥 | 是（如果EMBEDDING_PROVIDER=gemini） | |

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

| 从Huggingface打开模型 | 是（如果EMBEDDING_PROVIDER=huggingface） | |

示例

  • 文件 支持嵌入（OpenAI）： .python-version不支持嵌入：
  • 安装与设置 要求 Python 3.11(见
  • ）

紫外线

  1. （依赖管理器；

  2. 安装说明 uv )

    pip install uv

  3. MariaDB 服务器（本地或远程）

    uv pip compile pyproject.toml -o uv.lock

    uv pip sync uv.lock

  4. 步骤 .env 克隆仓库 安装（如果尚未）：

  5. 安装依赖项

    创造

    python server.py

    在项目根目录（参见

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

    配置

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

)

运行服务器

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

SSE 交通（或：SSE 运输部门）

{
  "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"}]
  }
}

HTTP传输（可流式传输的HTTP）：

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

使用示例

标准SQL查询

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

创建向量存储

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

将文档插入向量存储

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

语义搜索

  • 集成 - Claude桌面版/Cursor/Windsurf/VSCode logs/mcp_server.log 选项1：直接命令（标准输入输出）
  • 选项2：SSE传输
  • 选项3：HTTP传输 config.py 记录日志

日志被写入到

  • 默认情况下。 src/tests/ 日志消息包括工具调用、配置问题、嵌入错误以及客户端请求。
  • 日志级别和输出可以在代码中进行调整（参见 src/tests/README.md 以及日志记录器的设置）。
  • 测试

相关 MCP