MCP MariaDB Server

You can run the MCP MariaDB Server to manage MariaDB databases through a unified Model Context Protocol interface, with optional vector/embedding search capabilities. This lets you perform safe read-only SQL queries, explore schemas, and, if enabled, perform embedding-based document search over vector stores from a single MCP endpoint.

How to use

Connect to the MCP MariaDB Server using an MCP client to access standard database operations and optional vector search features. You can list databases and tables, inspect schemas, execute safe read-only SQL queries, and manage vector stores for embeddings. If embedding providers are configured, you can create and query vector stores to perform semantic search over documents. Use the HTTP transport endpoints for remote access, or the standard input/output (stdio) transport for local usage.

How to install

Prerequisites: you need Python 3.11 and a MariaDB server (local or remote). You also install the uv dependency manager to run the MCP server.

# Install uv if you don’t have it
pip install uv

# Install project dependencies and lock file
uv lock
uv sync

# Create configuration file with environment variables (see configuration section)
# Then start the MCP server in stdio (local) mode
uv run server.py

# Optional: start with SSE transport
uv run server.py --transport sse --host 127.0.0.1 --port 9001

# Optional: start with HTTP transport
uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp

Configuration

All settings are provided via environment variables. Critical values include database connection details, read-only mode, and optional embedding provider configuration. If you enable SSL/TLS for the database connection, you provide CA and client certificates as needed.

Key environment variables include:

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

# Optional embedding provider configuration
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
HF_MODEL="BAAI/bge-m3"

Using standard database tools

You can perform common database operations through the MCP interface. The following capabilities are available:

• List all accessible databases
• List tables in a chosen database
• Retrieve table schemas and relations
• Execute read-only SQL queries (SELECT, SHOW, DESCRIBE) in a safe, read-only mode if MCP_READ_ONLY is enabled
• Create new databases when needed

Available tools

list_databases

Lists all accessible databases.

list_tables

Lists all tables in a specified database.

get_table_schema

Retrieves schema for a table including columns, types, and keys.

get_table_schema_with_relations

Retrieves table schema with foreign key relations.

execute_sql

Executes a read-only SQL query (SELECT, SHOW, DESCRIBE) with optional parameters and read-only enforcement.

create_database

Creates a new database if it does not exist.

create_vector_store

Creates a new vector store for embeddings (if embedding support is enabled).

delete_vector_store

Deletes a vector store (table).

list_vector_stores

Lists all vector stores in a database.

insert_docs_vector_store

Batch inserts documents into a vector store with optional metadata.

search_vector_store

Performs semantic search over a vector store using embeddings.