mariadb-mcp

MariaDB MCP 服务

最后更新：2026-05-25

模型上下文协议（MCP）可让 AI Agent 连接外部工具和数据源。MariaDB MCP 服务为 Agent 提供对 MariaDB 数据库的直接、受控访问，可读取架构、运行查询，并可选择进行向量／语义搜索，无需开发者编写集成代码。

该服务采用开源 MIT 许可证，由 MariaDB Foundation 维护，项目地址：github.com/MariaDB/mcp。

要求： Python 3.11+、uv 包管理器、MariaDB 服务。

Agent 可以执行的操作

连接 MariaDB MCP 服务后，Agent 可以：

• 列出数据库和表
• 读取表架构，包括外键关系
• 运行只读 SQL 查询（SELECT、SHOW、DESCRIBE）
• 创建数据库
• 对存储的文档进行语义／向量搜索（需配置嵌入提供方）

默认情况下，写入操作（INSERT、UPDATE、DELETE）处于禁用状态。

安装

git clone https://github.com/MariaDB/mcp
cd mcp
cp .env.example .env
# Edit .env with your database credentials

最低限度的 .env 配置：

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=myuser
DB_PASSWORD=mypassword
DB_NAME=mydatabase
MCP_READ_ONLY=true

运行服务：

uv run server.py

连接 Claude Code、Cursor 或 Windsurf

从本地克隆的仓库使用官方服务（见“安装”）。将 MCP 配置指向 uv run server.py 和包含数据库凭据的 .env 文件。

Claude Code（位于仓库根目录的项目级 .mcp.json）：

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

也可以通过 CLI 添加（替换路径）：

claude mcp add mariadb -- uv --directory /absolute/path/to/mcp run server.py

Cursor / VS Code — 在 MCP 设置中使用相同的 mcpServers 配置块；请使用绝对路径。

SSE 或 HTTP — 运行 uv run server.py --transport sse（或 http），并连接到相应 URL；请参阅 MariaDB/mcp README — 集成。

非官方： PyPI 软件包 mcp-server-mariadb（uvx mcp-server-mariadb）是第三方项目，并非由 MariaDB Foundation 维护。除非有特定理由使用 PyPI 软件包，否则建议使用 github.com/MariaDB/mcp。

可用工具

工具	功能
list_databases	列出用户可访问的所有数据库
list_tables	列出数据库中的表
get_table_schema	返回列定义和类型
get_table_schema_with_relations	包含外键关系
execute_sql	运行只读 SQL 查询
create_database	创建新数据库

向量与语义搜索（可选）

配置嵌入提供方后，即可通过 MCP 接口直接构建 RAG 工作流，并使用以下额外工具：

工具	功能
create_vector_store	创建向量存储表
insert_docs_vector_store	为文档生成嵌入并存储
search_vector_store	进行语义相似度搜索
list_vector_stores	列出可用的向量存储
delete_vector_store	删除向量存储

在 .env 中配置嵌入提供方：

EMBEDDING_PROVIDER=openai   # or gemini or huggingface
OPENAI_API_KEY=sk-...

构建纯向量搜索应用时，直接使用 MariaDB 原生 VECTOR 类型和 VEC_DISTANCE_* 函数效率更高。MCP 向量工具适用于快速原型开发，也适用于需要由 AI Agent 自行管理向量存储的场景。原生向量 SQL 请参阅 mariadb-vector 技能。

安全：只读访问

MCP_READ_ONLY=true 设置会在应用层筛选查询，以强制实现只读。对于生产环境或共享环境，还应在数据库层进行限制：

CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'password';
GRANT SELECT, SHOW DATABASES ON *.* TO 'mcp_agent'@'localhost';
-- Do NOT grant INSERT, UPDATE, DELETE, DROP

仅依靠应用层的只读限制并不充分；数据库层的权限才是可靠保障。

关键注意事项

• 必须使用 uv：MCP 服务使用 uv 管理依赖，而非直接使用 pip。安装方式：pip install uv 或 brew install uv。
• 软件层面无法完全强制只读：应依赖数据库级权限，而不只是设置 MCP_READ_ONLY=true。
• 向量工具默认禁用，直到在 .env 中设置 EMBEDDING_PROVIDER。
• 连接池默认最多 10 个连接——并发使用 Agent 时，可调整 MCP_MAX_POOL_SIZE。
• SSL/TLS：对于远程或生产数据库，请在 .env 中配置 DB_SSL_CA、DB_SSL_CERT 和 DB_SSL_KEY。
• 企业版：MariaDB 还提供 MariaDB Enterprise MCP Server，具备更多访问控制和多 Agent 功能。请参阅 mariadb.com/products/mcp-server。

来源

• MariaDB MCP Server — GitHub
• MariaDB MCP Server 产品页面 — mariadb.com
• 通过 MCP 将 Claude Code 连接到工具 — Claude Code 文档

此处未涵盖的主题，请参阅 MariaDB 官方文档：mariadb.com/docs。