MCP MariaDB Server

The MCP MariaDB Server exposes a set of tools for interacting with MariaDB databases and vector stores via a standardized protocol. It supports:

- Listing databases and tables
- Retrieving table schemas
- Executing safe, read-only SQL queries
- Creating and managing vector stores for embedding-based search
- Integrating with embedding providers (currently OpenAI, Gemini, and HuggingFace) (optional)

- server.py: Main MCP server logic and tool definitions.
- config.py: Loads configuration from environment and.envfiles.
- embeddings.py: Handles embedding service integration (OpenAI).
- tests/: Manual and automated test documentation and scripts.

- Lists all accessible databases.
- Parameters:None

- Lists all tables in a specified database.
- Parameters:database_name(string, required)

- Retrieves schema for a table (columns, types, keys, etc.).
- Parameters:database_name(string, required),table_name(string, required)

- Retrieves schema with foreign key relations for a table.
- Parameters:database_name(string, required),table_name(string, required)

- Executes a read-only SQL query (SELECT,SHOW,DESCRIBE).
- Parameters:sql_query(string, required),database_name(string, optional),parameters(list, optional)
- Note: Enforces read-only mode ifMCP_READ_ONLYis enabled.

- Creates a new database if it doesn't exist.
- Parameters:database_name(string, required)

Vector Store & Embedding Tools (optional)

Note: These tools are only available whenEMBEDDING_PROVIDERis configured. If no embedding provider is set, these tools will be disabled.

- Creates a new vector store (table) for embeddings.
- Parameters:database_name,vector_store_name,model_name(optional),distance_function(optional, default: cosine)

- Deletes a vector store (table).
- Parameters:database_name,vector_store_name

- Lists all vector stores in a database.
- Parameters:database_name

- Batch inserts documents (and optional metadata) into a vector store.
- Parameters:database_name,vector_store_name,documents(list of strings),metadata(optional list of dicts)

- Performs semantic search for similar documents using embeddings.
- Parameters:database_name,vector_store_name,user_query(string),k(optional, default: 7)

The MCP MariaDB Server providesoptionalembedding and vector store capabilities. These features can be enabled by configuring an embedding provider, or completely disabled if you only need standard database operations.

- OpenAI
- Gemini
- Open models from Huggingface

- EMBEDDING_PROVIDER: Set toopenai,gemini,huggingface, or leave unset to disable
- OPENAI_API_KEY: Required if using OpenAI embeddings
- GEMINI_API_KEY: Required if using Gemini embeddings
- HF_MODEL: Required if using HuggingFace embeddings (e.g., "intfloat/multilingual-e5-large-instruct" or "BAAI/bge-m3")

- Default and allowed models are configurable in code (DEFAULT_OPENAI_MODEL,ALLOWED_OPENAI_MODELS)
- Model can be selected per request or defaults to the configured model

A vector store table has the following columns:

- id: Auto-increment primary key
- document: Text of the document
- embedding: VECTOR type (indexed for similarity search)
- metadata: JSON (optional metadata)

Configuration & Environment Variables

All configuration is via environment variables (typically set in a.envfile):

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"

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

DB_HOST=your-remote-host.com DB_USER=your_db_user DB_PASSWORD=your_db_password DB_PORT=3306 DB_NAME=your_default_database # Enable SSL DB_SSL=true DB_SSL_CA=~/.mysql/ca-cert.pem DB_SSL_CERT=~/.mysql/client-cert.pem DB_SSL_KEY=~/.mysql/client-key.pem DB_SSL_VERIFY_CERT=true DB_SSL_VERIFY_IDENTITY=false MCP_READ_ONLY=true MCP_MAX_POOL_SIZE=10

- All SSL certificate paths support~for home directory expansion
- DB_SSL_CAis used to verify the server's certificate
- DB_SSL_CERTandDB_SSL_KEYare used for client certificate authentication (mutual TLS)
- SetDB_SSL_VERIFY_CERT=falseonly for testing with self-signed certificates
- SetDB_SSL_VERIFY_IDENTITY=trueto enable strict hostname verification

Example Authentication Configuration:This configuration uses external web authentication via GitHub or Google. If you have internal JWT authentication (desired for organizations who manage their own services), you can use the JWT provider instead.

# GitHub OAuth export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..." export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="github_pat_..." # Google OAuth export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="123456.apps.googleusercontent.com" export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="GOCSPX-..."

⚠️ The only way to guarantee 100% read-only access with absolute certainty is to configure the MariaDB user with appropriate privileges.The READ_ONLY flag is a best effort attempt to prevent write operations, but it is based upon a whitelist of allowed queries and against a truly adversarial user it is not a substitute for proper database user privileges.

For production use, you should create a dedicated database user with minimal privileges. This is also recommended to show the LLM only the data it may need to perform its task even outside of read-only mode.

uv run server.py --transport sse --host 127.0.0.1 --port 9001

uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp