MariaDB MCP Server for SQL and Vector Search

Overview

The MariaDB MCP Server implements the Model Context Protocol (MCP) for MariaDB, exposing a standardized set of tools to manage and query relational data and optional embedding-based vector stores. It is designed to be used by AI assistants or other MCP-compatible clients so they can combine traditional SQL workflows (schema discovery, read-only queries) with semantic search powered by embeddings stored in MariaDB VECTOR columns.

By providing the same MCP interface for both SQL and vector search, the server makes it straightforward to augment existing database-driven applications with embedding search (semantic similarity, retrieval-augmented generation) without changing developer workflows or introducing separate vector databases.

Repository: https://github.com/mariadb/mcp Tags: ai-ml, database, search

Features

• List databases and tables, and inspect table schemas (including foreign-key relations).
• Execute safe, read-only SQL queries (SELECT, SHOW, DESCRIBE) with optional parameter binding.
• Create and manage vector store tables that hold embeddings alongside documents and metadata.
• Batch insert documents with embeddings and perform k-nearest-neighbor semantic search.
• Optional integration with embedding providers (OpenAI, Gemini, Hugging Face).
• Configuration via environment variables and .env files; read-only enforcement via MCP_READ_ONLY.

Installation / Configuration

Prerequisites: Python 3.8+, a MariaDB server (or compatible MySQL server), and optional API keys for embedding providers.

1. Clone the repo and install dependencies:

git clone https://github.com/mariadb/mcp.git
cd mcp
pip install -r requirements.txt

2. Example .env (create a .env file or export env vars):

# Database connection
DB_HOST=localhost
DB_PORT=3306
DB_USER=mcp_user
DB_PASSWORD=secret
DB_NAME=default_db

# Server behavior
MCP_READ_ONLY=true

# Optional embeddings provider (leave unset to disable)
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
DEFAULT_OPENAI_MODEL=text-embedding-3-small

3. Start the MCP server (example):

python server.py

The server loads configuration from environment variables; embedding-related tools are enabled only when EMBEDDING_PROVIDER is set.

Configuration Reference

Available Tools / Resources

Standard relational tools:

• list_databases — enumerate accessible databases.
• list_tables(database_name) — list tables in a database.
• get_table_schema(database_name, table_name) — column definitions, types, keys.
• get_table_schema_with_relations(database_name, table_name) — schema + foreign keys.
• execute_sql(sql_query, database_name?, parameters?) — read-only SQL execution.
• create_database(database_name) — create database if not present.

Vector store / embedding tools (enabled only with EMBEDDING_PROVIDER):

• create_vector_store(database_name, vector_store_name, model_name?, distance_function?)
• delete_vector_store(database_name, vector_store_name)
• list_vector_stores(database_name)
• insert_docs_vector_store(database_name, vector_store_name, documents[], metadata[]?)
• search_vector_store(database_name, vector_store_name, user_query, k=7)

Vector store schema (typical):

• id: AUTO_INCREMENT PRIMARY KEY
• document: TEXT
• embedding: VECTOR (indexed for similarity search)
• metadata: JSON (optional)

Example tool payload (MCP-style JSON, transport depends on your MCP client):

{
  "tool": "execute_sql",
  "parameters": {
    "sql_query": "SELECT id, title FROM articles WHERE published = 1 LIMIT 10",
    "database_name": "content_db"
  }
}

Use Cases

• Semantic augmentation of search: create a vector store for article content, index embeddings, and combine structured SQL filters with semantic vector rankings to present relevant results.
• Read-only analytics and schema inspection: use list_tables and get_table_schema_with_relations for automated agent planning, UI generation, or migration analysis.
• Retrieval-augmented generation (RAG): store document passages and metadata in a vector table, retrieve top-k semantically similar passages, and feed them to an LLM along with SQL query results.
• Safe data access for assistants: enforce MCP_READ_ONLY to prevent accidental data mutations while enabling rich data exploration.

Best Practices & Security

• Use MCP_READ_ONLY=true for production deployments where agents should not modify data.
• Restrict database credentials and rotate API keys for embedding providers.
• Enable TLS/SSL for MariaDB (DB_SSL and DB_SSL_CA) when connecting across untrusted networks.
• Limit allowed embedding models and rate-limit embedding requests to control costs.

For implementation details, examples, and tests, see the repository: https://github.com/mariadb/mcp.