mcp-server-mariadb-vector

注意：

MariaDB チームがこのハッカソンプロジェクトを引き継ぎ、大幅に改良しました。詳しくは https://github.com/MariaDB/mcp をご覧ください。

私の作業を紹介するため、このリポジトリは公開したままにしています。MariaDB チームがこのプロジェクトについて書いたブログ記事はこちらです：https://mariadb.org/model-context-protocol-mcp-hackathon-integration-track-winner/

mcp-server-mariadb-vector

MariaDB Vector MCP サーバーは、LLM エージェントがベクトルをサポートする MariaDB データベースとやり取りするためのツールを提供し、ユーザーが自然言語のインターフェースを使ってデータを保存し、操作できるようにします。Model Context Protocol（MCP）のおかげで、このサーバーは、Claude Desktop や Cursor/Windsurf などのアプリケーションが提供するものを含むあらゆる MCP クライアントに加え、LangGraph や PydanticAI などの LLM エージェントフレームワークとも互換性があります。

MariaDB Vector MCP サーバーを使用すると、たとえば次のことができます。

• ナレッジベースのコンテキストを LLM エージェントとの会話に提供する
• LLM エージェントとの会話を保存して検索する

機能

• ベクトルストアの管理

  • 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 を使ってすばやく起動できます。

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 コンテナとして実行する方法の 2 つです。

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

サーバーは SSE トランスポートプロトコルを使用して http://localhost:8000/sse で利用できます。ホストマシン上で MariaDB データベースを Docker コンテナとして実行している場合は、MARIADB_HOST を host.docker.internal に設定したままにしてください。

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