mcp-server-mariadb-vector

说明：

MariaDB 团队接手了这个黑客松项目，并对其进行了大幅改进，你可以在此查看：https://github.com/MariaDB/mcp。

我保留此仓库公开，以展示我的工作，并附上他们为此撰写的博客链接：https://mariadb.org/model-context-protocol-mcp-hackathon-integration-track-winner/

mcp-server-mariadb-vector

MariaDB Vector MCP 服务提供了一组工具，LLM Agent 可以使用这些工具与支持向量功能的 MariaDB 数据库交互，为用户提供一种通过自然语言存储和操作数据的方式。得益于 Model Context Protocol（MCP），此服务兼容任何 MCP 客户端，包括 Claude Desktop 和 Cursor/Windsurf 等应用提供的客户端，以及 LangGraph 和 PydanticAI 等 LLM Agent 框架。

例如，使用 MariaDB Vector MCP 服务，用户可以：

• 将知识库中的上下文提供给 LLM Agent 的对话
• 存储和查询与 LLM Agent 的对话

功能

• 向量存储管理

  • 在 MariaDB 数据库中创建和删除向量存储
  • 列出 MariaDB 数据库中的所有向量存储

• 文档管理

  • 向向量存储添加带有可选元数据的文档
  • 使用语义搜索查询向量存储

• 嵌入提供方

  • 使用 OpenAI 的嵌入模型生成文档嵌入

MCP 工具

• mariadb_create_vector_store：在 MariaDB 数据库中创建向量存储
• mariadb_delete_vector_store：删除 MariaDB 数据库中的向量存储
• mariadb_list_vector_stores：列出 MariaDB 数据库中的所有向量存储
• mariadb_insert_documents：向向量存储添加带有可选元数据的文档
• mariadb_search_vector_store：使用语义搜索查询向量存储

设置

注意： 从这里开始，假定你已有一个正在运行且支持向量功能的 MariaDB 实例（版本 11.7 或更高版本）。如果没有，可以使用 Docker 快速启动 MariaDB 实例：

docker run -p 3306:3306 --name mariadb-instance -e MARIADB_ROOT_PASSWORD=password -e MARIADB_DATABASE=database_name mariadb:11.7

首先克隆仓库：

git clone https://github.com/DavidRamosSal/mcp-server-mariadb-vector.git

运行 MariaDB Vector MCP 服务有两种方式：使用 uv 作为 Python 包运行，或使用提供的 Dockerfile 构建 Docker 容器运行。

使用 uv 运行服务的要求

• MariaDB Connector/C - 安装说明
• uv - 安装说明

将服务作为 Docker 容器运行的要求

• Docker - 安装说明

配置

服务需要配置以下环境变量：

名称	描述	默认值
MARIADB_HOST	正在运行的 MariaDB 数据库的主机	127.0.0.1
MARIADB_PORT	正在运行的 MariaDB 数据库的端口	3306
MARIADB_USER	正在运行的 MariaDB 数据库的用户	None
MARIADB_PASSWORD	正在运行的 MariaDB 数据库的密码	None
MARIADB_DATABASE	正在运行的 MariaDB 数据库的名称	None
EMBEDDING_PROVIDER	嵌入模型的提供方	openai
EMBEDDING_MODEL	嵌入提供方的模型	text-embedding-3-small
OPENAI_API_KEY	OpenAI 平台的 API 密钥	None

使用 uv 运行服务

使用 uv，你可以在克隆的仓库根目录中添加一个包含环境变量的 .env 文件，并运行以下命令启动服务：

uv run --dir path/to/mcp-server-mariadb-vector/ --env-file path/to/mcp-server-mariadb-vector/.env mcp_server_mariadb_vector

依赖项将自动安装。可以添加可选参数 --transport 来指定要使用的传输协议。默认值为 stdio。

将服务作为 Docker 容器运行

在克隆的仓库根目录中运行以下命令，构建 Docker 容器：

docker build -t mcp-server-mariadb-vector .

然后运行容器（替换为你自己的配置）：

docker run -p 8000:8000 \
  --add-host host.docker.internal:host-gateway \
  -e MARIADB_HOST="host.docker.internal" \
  -e MARIADB_PORT="port" \
  -e MARIADB_USER="user" \
  -e MARIADB_PASSWORD="password" \
  -e MARIADB_DATABASE="database" \
  -e EMBEDDING_PROVIDER="openai" \
  -e EMBEDDING_MODEL="embedding-model" \
  -e OPENAI_API_KEY="your-openai-api-key" \
  mcp-server-mariadb-vector

服务将在 http://localhost:8000/sse 上提供，使用 SSE 传输协议。请务必将 MARIADB_HOST 保持为 host.docker.internal，前提是你在主机上以 Docker 容器的形式运行 MariaDB 数据库。

与 Claude Desktop | Cursor | Windsurf 集成

Claude Desktop、Cursor 和 Windsurf 可以使用 stdio 传输自动运行并连接到服务。为此，请将以下内容添加到配置文件中（Claude Desktop 使用 claude_desktop_config.json，Cursor 使用 mcp.json，Windsurf 使用 mcp_config.json）：

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

或者，Cursor 和 Windsurf 可以使用 SSE 传输连接到主机上已运行的服务（例如，以 Docker 容器的形式运行服务时）。为此，请将以下内容添加到相应的配置文件中：

  "mcpServers": {
    "mariadb-vector": {
      "url": "http://localhost:8000/sse"
    }
  }
}