by MariaDB
Provides a Model Context Protocol interface for managing and querying MariaDB databases, supporting standard SQL operations and embedding‑based vector search.
MCP MariaDB Server exposes a set of tools that allow callers to list databases, inspect table schemas, run read‑only SQL queries, and optionally create and query vector stores powered by embedding providers such as OpenAI, Gemini, or HuggingFace. The server follows the Model Context Protocol, making it easy to integrate with AI assistants and other LLM‑driven workflows.
git clone https://github.com/MariaDB/mcp.git
cd mcp
uv
)
pip install uv
uv pip compile pyproject.toml -o uv.lock
uv pip sync uv.lock
.env
file at the project root with the required connection parameters and, if needed, embedding credentials (see the "Configuration & Environment Variables" table in the README).python server.py
The server will listen for MCP requests (default SSE endpoint http://localhost:9001/sse
).execute_sql
, create_vector_store
, search_vector_store
, etc.MCP_READ_ONLY
flag..env
file.logs/mcp_server.log
with detailed request and error information.EMBEDDING_PROVIDER
and model names without code changes.Q: Do I need an embedding provider to use the server?
A: No. Vector‑store tools are disabled unless EMBEDDING_PROVIDER
is set. All standard SQL tools work independently.
Q: Can I run write queries (INSERT/UPDATE)?
A: The server only exposes read‑only SQL (SELECT
, SHOW
, DESCRIBE
). Write operations must be performed outside the MCP interface.
Q: How is the vector similarity computed?
A: The server stores embeddings in a MariaDB VECTOR
column and uses the configured distance_function
(default: cosine) for nearest‑neighbor search.
Q: Which Python version is required?
A: Python 3.11 as defined in .python-version
.
Q: Where are logs stored?
A: By default to logs/mcp_server.log
. Log level can be adjusted in config.py
.
Q: How do I change the server port?
A: The port is hard‑coded in server.py
or can be overridden by editing the launch command; there is no dedicated environment variable.
The MCP MariaDB Server provides a Model Context Protocol (MCP) interface for managing and querying MariaDB databases, supporting both standard SQL operations and advanced vector/embedding-based search. Designed for use with AI assistants, it enables seamless integration of AI-driven data workflows with relational and vector databases.
The MCP MariaDB Server exposes a set of tools for interacting with MariaDB databases and vector stores via a standardized protocol. It supports:
.env
files.list_databases
list_tables
database_name
(string, required)get_table_schema
database_name
(string, required), table_name
(string, required)get_table_schema_with_relations
database_name
(string, required), table_name
(string, required)execute_sql
SELECT
, SHOW
, DESCRIBE
).sql_query
(string, required), database_name
(string, optional), parameters
(list, optional)MCP_READ_ONLY
is enabled.create_database
database_name
(string, required)Note: These tools are only available when EMBEDDING_PROVIDER
is configured. If no embedding provider is set, these tools will be disabled.
create_vector_store
database_name
, vector_store_name
, model_name
(optional), distance_function
(optional, default: cosine)delete_vector_store
database_name
, vector_store_name
list_vector_stores
database_name
insert_docs_vector_store
database_name
, vector_store_name
, documents
(list of strings), metadata
(optional list of dicts)search_vector_store
database_name
, vector_store_name
, user_query
(string), k
(optional, default: 7)The MCP MariaDB Server provides optional embedding and vector store capabilities. These features can be enabled by configuring an embedding provider, or completely disabled if you only need standard database operations.
EMBEDDING_PROVIDER
: Set to openai
, gemini
, huggingface
, or leave unset to disableOPENAI_API_KEY
: Required if using OpenAI embeddingsGEMINI_API_KEY
: Required if using Gemini embeddingsHF_MODEL
: Required if using HuggingFace embeddings (e.g., "intfloat/multilingual-e5-large-instruct" or "BAAI/bge-m3")DEFAULT_OPENAI_MODEL
, ALLOWED_OPENAI_MODELS
)A vector store table has the following columns:
id
: Auto-increment primary keydocument
: Text of the documentembedding
: VECTOR type (indexed for similarity search)metadata
: JSON (optional metadata)All configuration is via environment variables (typically set in a .env
file):
Variable | Description | Required | Default |
---|---|---|---|
DB_HOST |
MariaDB host address | Yes | localhost |
DB_PORT |
MariaDB port | No | 3306 |
DB_USER |
MariaDB username | Yes | |
DB_PASSWORD |
MariaDB password | Yes | |
DB_NAME |
Default database (optional; can be set per query) | No | |
DB_CHARSET |
Character set for database connection (e.g., cp1251 ) |
No | MariaDB default |
MCP_READ_ONLY |
Enforce read-only SQL mode (true /false ) |
No | true |
MCP_MAX_POOL_SIZE |
Max DB connection pool size | No | 10 |
EMBEDDING_PROVIDER |
Embedding provider (openai /gemini /huggingface ) |
No | None (Disabled) |
OPENAI_API_KEY |
API key for OpenAI embeddings | Yes (if EMBEDDING_PROVIDER=openai) | |
GEMINI_API_KEY |
API key for Gemini embeddings | Yes (if EMBEDDING_PROVIDER=gemini) | |
HF_MODEL |
Open models from Huggingface | Yes (if EMBEDDING_PROVIDER=huggingface) |
.env
fileWith Embedding Support (OpenAI):
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"
Without Embedding Support:
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
.python-version
)uv
(if not already):
pip install uv
uv pip compile pyproject.toml -o uv.lock
uv pip sync uv.lock
.env
in the project root (see Configuration)python server.py
Adjust entry point if needed (e.g., main.py
){
"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"
}
}
{
"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"}]
}
}
{
"tool": "search_vector_store",
"parameters": {
"database_name": "test_db",
"vector_store_name": "my_vectors",
"user_query": "What is the capital of France?",
"k": 5
}
}
{
"mcpServers": {
"MariaDB_Server": {
"command": "uv",
"args": [
"--directory",
"path/to/mariadb-mcp-server/",
"run",
"server.py"
],
"envFile": "path/to/mcp-server-mariadb-vector/.env"
}
}
}
or If already running MCP server
{
"servers": {
"mariadb-mcp-server": {
"url": "http://{host}:9001/sse",
"type": "sse"
}
}
}
logs/mcp_server.log
by default.config.py
and logger setup).src/tests/
directory.src/tests/README.md
for an overview.Please log in to share your review and rating for this MCP.
{ "mcpServers": { "mariadb-mcp-server": { "command": "python", "args": [ "server.py" ], "env": { "DB_HOST": "<HOST>", "DB_USER": "<USER>", "DB_PASSWORD": "<PASSWORD>", "EMBEDDING_PROVIDER": "<PROVIDER_OPTIONAL>", "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>" } } } }
Discover more MCP servers with similar functionality and use cases
by googleapis
Provides a configurable MCP server that abstracts connection pooling, authentication, observability, and tool management to accelerate development of database‑backed AI tools.
by bytebase
DBHub is a universal database gateway that implements the Model Context Protocol (MCP) server interface, enabling MCP-compatible clients to interact with various databases.
by neo4j-contrib
Provides Model Context Protocol servers for interacting with Neo4j databases, managing Aura instances, and handling personal knowledge graph memory through natural‑language interfaces.
by mongodb-js
Provides a Model Context Protocol server that connects to MongoDB databases and Atlas clusters, exposing a rich set of tools for querying, managing, and administering data and infrastructure.
by benborla
A Model Context Protocol (MCP) server that provides read-only access to MySQL databases, enabling Large Language Models (LLMs) to inspect database schemas and execute read-only queries.
by ClickHouse
Provides tools that let AI assistants run read‑only SQL queries against ClickHouse clusters or the embedded chDB engine, plus a health‑check endpoint for service monitoring.
by elastic
Provides direct, natural‑language access to Elasticsearch indices via the Model Context Protocol, allowing AI agents to query and explore data without writing DSL.
by motherduckdb
Provides an MCP server that enables SQL analytics on DuckDB and MotherDuck databases, allowing AI assistants and IDEs to execute queries via a unified interface.
by redis
Provides a natural language interface for agentic applications to manage and search data in Redis efficiently.