mcp

MariaDB MCP (Model Context Protocol) server implementation

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio mariadb-mcp python server.py \
  --env DB_SSL="Enable SSL/TLS for DB connection (true/false, optional)" \
  --env DB_HOST="MariaDB host address (required)" \
  --env DB_NAME="Default database (optional)" \
  --env DB_PORT="MariaDB port (optional, default 3306)" \
  --env DB_USER="MariaDB username (required)" \
  --env HF_MODEL="HuggingFace model name (required if EMBEDDING_PROVIDER=huggingface)" \
  --env DB_SSL_CA="Path to CA certificate (optional)" \
  --env DB_CHARSET="Character set for connection (optional)" \
  --env DB_SSL_KEY="Path to client key (optional)" \
  --env DB_PASSWORD="MariaDB password (required)" \
  --env DB_SSL_CERT="Path to client certificate (optional)" \
  --env ALLOWED_HOSTS="Comma-separated allowed hosts (optional)" \
  --env MCP_READ_ONLY="Enforce read-only mode (true/false, optional; default true)" \
  --env GEMINI_API_KEY="API key for Gemini embeddings (required if EMBEDDING_PROVIDER=gemini)" \
  --env OPENAI_API_KEY="API key for OpenAI embeddings (required if EMBEDDING_PROVIDER=openai)" \
  --env ALLOWED_ORIGINS="Comma-separated allowed origins (optional)" \
  --env MCP_MAX_POOL_SIZE="Max DB connection pool size (optional)" \
  --env DB_SSL_VERIFY_CERT="Verify server certificate (true/false, optional)" \
  --env EMBEDDING_PROVIDER="Embedding provider (openai/gemini/huggingface) or leave unset to disable" \
  --env DB_SSL_VERIFY_IDENTITY="Verify server hostname (true/false, optional)"

How to use

This MCP server exposes a MariaDB database interface via the MCP protocol, enabling standard relational database operations alongside optional vector-embed capabilities. You can list databases and tables, fetch table schemas (with or without foreign key relations), and execute safe read-only SQL queries. When embedding is configured, you also gain access to vector store tools for creating, listing, inserting documents, and performing semantic searches over embeddings. Use the vector store tools to store document embeddings in MariaDB and leverage similarity search to retrieve relevant records or documents in context to user queries. The server integrates with embedding providers such as OpenAI, Gemini, or HuggingFace, if configured, enabling semantic search alongside traditional SQL queries.

How to install

Prerequisites:

Python 3.8+ installed on your system
MariaDB server reachable with credentials you provide
Access to install Python dependencies (pip)

Clone the MCP MariaDB server repository (or download the package): git clone https://github.com/your-org/mcp-mariadb.git cd mcp-mariadb
Create and activate a Python virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # On Windows use: venv\Scripts\activate
Install dependencies pip install -r requirements.txt
Configure environment variables Create a .env file or export variables in your shell (example below): export DB_HOST=localhost export DB_USER=root export DB_PASSWORD=yourpassword export DB_NAME=mydatabase

Optional affiliate settings

export MCP_READ_ONLY=true

Embedding (optional)

export EMBEDDING_PROVIDER=openai

export OPENAI_API_KEY=sk-...
Run the MCP MariaDB server python server.py
(Optional) Run tests or examples if provided in tests/ directory

Additional notes

Notes:

Ensure that DB_HOST, DB_USER, and DB_PASSWORD are set; DB_NAME is optional and can be provided per-query.
MCP_READ_ONLY defaults to true to prevent unintended data modification; override if you need write access.
If embedding is enabled, ensure the corresponding API keys are set (OPENAI_API_KEY, GEMINI_API_KEY, or HF_MODEL for HuggingFace).
For security, configure ALLOWED_ORIGINS and ALLOWED_HOSTS as appropriate for your deployment.
When using HTTP or SSE transports, consider adding an authentication layer as described in the FastMCP docs to prevent unauthorized access.
The vector store features require the EMBEDDING_PROVIDER to be configured; otherwise, only standard database tools are available.

Related MCP Servers

mcp-vegalite

MCP server from isaacwasserman/mcp-vegalite-server

github-chat

A Model Context Protocol (MCP) for analyzing and querying GitHub repositories using the GitHub Chat API.

nautex

MCP server for guiding Coding Agents via end-to-end requirements to implementation plan pipeline

pagerduty

PagerDuty's official local MCP (Model Context Protocol) server which provides tools to interact with your PagerDuty account directly from your MCP-enabled client.

futu-stock

mcp server for futuniuniu stock

mcp -boilerplate

Boilerplate using one of the 'better' ways to build MCP Servers. Written using FastMCP

mcp