MCP MariaDB Server

How to use

You interact with the MCP MariaDB Server through an MCP client to explore databases, inspect table schemas, run safe read-only queries, and work with vector stores when embeddings are enabled. Use the available tools to list databases, view tables, fetch schemas, and execute SELECT-style queries. If you enable an embedding provider, you can create and search vector stores to perform semantic search over documents.

Typical usage patterns include discovering what data you have, inspecting table structures, validating queries against the read-only mode, and (when embeddings are configured) indexing documents into a vector store and performing semantic searches against that store.

How to install

Prerequisites you need before starting are a Python 3.11 runtime, the uv dependency manager, and access to a MariaDB server (local or remote). Ensure you have network access to your MariaDB host and the appropriate credentials.

Install the MCP server dependencies and set up the environment, then run the server to begin accepting MCP requests.

# Prerequisites
- Python 3.11
- uv (dependency manager)
- MariaDB server access

# Install uv and dependencies
pip install uv
uv pip compile pyproject.toml -o uv.lock
uv pip sync uv.lock

# Create environment configuration
# Place environment variables in a .env file at the project root

# Run the server
python server.py

# If needed, adjust the entry point
# python main.py  (or another valid entry script)

Configuration & environment variables

All configuration is managed through environment variables. The server expects database connection details, read-only mode settings, pool sizing, and optional embedding provider configuration. Use a .env file to keep these values organized and secure.

Common environment variables you will set include the MariaDB host, port, user, and password, plus optional settings for read-only mode and the embedding provider. The following are defined for reference.

DB_HOST=localhost
DB_PORT=3306
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_NAME=your_default_database
MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10
EMBEDDING_PROVIDER=openai  # or gemini or huggingface
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
HF_MODEL="BAAI/bge-m3"

Usage notes and tips

If you enable embedding features, provide the appropriate API keys or model identifiers for your chosen provider. When embeddings are not configured, you can rely solely on standard SQL operations.

The server enforces read-only mode when MCP_READ_ONLY is enabled, helping to protect your data while you perform queries and inspections.

Logging and troubleshooting

Logs are written to a file named mcp_server.log under the logs directory by default. Logs capture tool invocations, configuration issues, embedding provider errors, and client requests to help with troubleshooting.

If you encounter connectivity or permission errors, verify that DB_HOST, DB_USER, and DB_PASSWORD are correct, that MCP_READ_ONLY is set appropriately, and that the user has the necessary privileges on the target database.

Testing and validation

Use the standard tools to list databases, fetch table schemas, and run safe read-only queries to validate your setup before introducing vector store operations.

list_databases

Lists all accessible databases.

list_tables

Lists all tables in a specified database.

get_table_schema

Retrieves the schema for a table (columns, types, keys, etc.).

get_table_schema_with_relations

Retrieves the schema with foreign key relations for a table.

execute_sql

Executes a read-only SQL query (SELECT, SHOW, DESCRIBE). Enforces read-only mode when MCP_READ_ONLY is enabled.

create_database

Creates a new database if it doesn't exist.

create_vector_store

Creates a new vector store (table) for embeddings (optional).

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 on a vector store using embeddings.