MCP MariaDB Server

What is MCP MariaDB Server about?

MCP MariaDB Server exposes a set of standardized tools that let you list databases and tables, retrieve schemas, execute read‑only SQL, and, when an embedding provider is configured, create and query vector stores for semantic search. It is designed for integration with AI assistants and other automation pipelines that need seamless access to relational data and embeddings.

How to use MCP MariaDB Server?

Clone the repository and ensure Python 3.11 is installed.
Install the dependency manager uv and run:
```
uv lock
uv sync
```
Create a .env file with the required connection parameters (e.g., DB_HOST, DB_USER, DB_PASSWORD) and optional embedding settings (EMBEDDING_PROVIDER, OPENAI_API_KEY, etc.).

Start the server (default stdio transport):

uv run server.py

Alternative transports:

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

Invoke tools via the MCP protocol from a client (e.g., Claude, Cursor, VS Code) by sending JSON payloads such as:

{ "tool": "execute_sql", "parameters": { "database_name": "test", "sql_query": "SELECT * FROM users" } }

Key features of MCP MariaDB Server

Standard Database Operations: list databases/tables, fetch table schemas, create databases, execute read‑only SQL queries.
Read‑Only Enforcement: optional MCP_READ_ONLY flag prevents data‑modifying statements.
Vector Store Management (optional): create/delete vector stores, batch‑insert documents with embeddings, and perform k‑nearest‑neighbor searches.
Multiple Embedding Providers: OpenAI, Gemini, and HuggingFace models can be plugged in via environment variables.
Configurable via .env: all connection, pooling, and embedding settings are environment‑driven.
Multiple Transport Options: standard I/O, Server‑Sent Events (SSE), and streamable HTTP.
Logging: writes detailed logs to logs/mcp_server.log for debugging and audit.

Use cases of MCP MariaDB Server

AI‑powered assistants that need to fetch relational data and augment it with semantic search results.
Data enrichment pipelines where documents are stored in MariaDB and later queried by meaning rather than exact text.
Knowledge bases combining structured tables with vector‑based retrieval for rapid answer generation.
Prototyping AI applications without building custom database‑to‑embedding glue layers.

FAQ for MCP MariaDB Server

Do I need an embedding provider to run the server? No. The server works for pure SQL operations; vector‑store tools are disabled when EMBEDDING_PROVIDER is unset.
Can I execute INSERT/UPDATE statements? Only if MCP_READ_ONLY is set to false. By default it is true to protect data.
Which distance functions are supported for vector search? The default is cosine, but you can specify any function supported by MariaDB’s VECTOR type (e.g., euclidean).
How are credentials protected? All secrets are loaded from environment variables or a .env file; avoid committing this file to version control.
Is authentication built‑in? The core server does not provide authentication; you can plug in FastMCP authentication providers as described in the README.

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.

Overview
Core Components
Available Tools
Embeddings & Vector Store
Configuration & Environment Variables
Installation & Setup
Usage Examples
Integration - Claude desktop/Cursor/Windsurf
Logging
Testing

Overview

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)

Core Components

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

Available Tools

Standard Database Tools

list_databases
- Lists all accessible databases.
- Parameters: None
list_tables
- Lists all tables in a specified database.
- Parameters: database_name (string, required)
get_table_schema
- Retrieves schema for a table (columns, types, keys, etc.).
- Parameters: database_name (string, required), table_name (string, required)
get_table_schema_with_relations
- Retrieves schema with foreign key relations for a table.
- Parameters: database_name (string, required), table_name (string, required)
execute_sql
- 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 if MCP_READ_ONLY is enabled.
create_database
- 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 when EMBEDDING_PROVIDER is configured. If no embedding provider is set, these tools will be disabled.

create_vector_store
- Creates a new vector store (table) for embeddings.
- Parameters: database_name, vector_store_name, model_name (optional), distance_function (optional, default: cosine)
delete_vector_store
- Deletes a vector store (table).
- Parameters: database_name, vector_store_name
list_vector_stores
- Lists all vector stores in a database.
- Parameters: database_name
insert_docs_vector_store
- 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)
search_vector_store
- Performs semantic search for similar documents using embeddings.
- Parameters: database_name, vector_store_name, user_query (string), k (optional, default: 7)

Embeddings & Vector Store

Overview

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.

Supported Providers

OpenAI
Gemini
Open models from Huggingface

Configuration

EMBEDDING_PROVIDER: Set to openai, 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")

Model Selection

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

Vector Store Schema

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 .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)
`ALLOWED_ORIGINS`	Comma-separated list of allowed origins	No	Long list of allowed origins corresponding to local use of the server
`ALLOWED_HOSTS`	Comma-separated list of allowed hosts	No	`localhost,127.0.0.1`

Note that if using 'http' or 'sse' as the transport, configuring authentication is important for security if you allow connections outside of localhost. Because different organizations use different authentication methods, the server does not provide a default authentication method. You will need to configure your own authentication method. Thankfully FastMCP provides a simple way to do this starting with version 2.12.1. See the FastMCP documentation for more information. We have provided an example configuration below.

Example `.env` file

With 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

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-..."

Installation & Setup

Requirements

Python 3.11 (see .python-version)
uv (dependency manager; install instructions)
MariaDB server (local or remote)

Steps

Clone the repository
Install uv (if not already):
```
pip install uv
```
Install dependencies
```
uv lock
uv sync
```
Create .env in the project root (see Configuration)

Run the server

Standard Input/Output (default):

uv run server.py

SSE Transport:

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

HTTP Transport (streamable HTTP):

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

Usage Examples

Standard SQL Query

{
  "tool": "execute_sql",
  "parameters": {
    "database_name": "test_db",
    "sql_query": "SELECT * FROM users WHERE id = %s",
    "parameters": [123]
  }
}

Create Vector Store

{
  "tool": "create_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "model_name": "text-embedding-3-small",
    "distance_function": "cosine"
  }
}

Insert Documents into Vector Store

{
  "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"}]
  }
}

Semantic Search

{
  "tool": "search_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "user_query": "What is the capital of France?",
    "k": 5
  }
}

Integration - Claude desktop/Cursor/Windsurf/VSCode

Option 1: Direct Command (stdio)

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mariadb-mcp-server/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

Option 2: SSE Transport

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/sse",
      "type": "sse"
    }
  }
}

Option 3: HTTP Transport

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/mcp",
      "type": "streamable-http"
    }
  }
}

Logging

Logs are written to logs/mcp_server.log by default.
Log messages include tool calls, configuration issues, embedding errors, and client requests.
Log level and output can be adjusted in the code (see config.py and logger setup).

Testing

Tests are located in the src/tests/ directory.
See src/tests/README.md for an overview.
Tests cover both standard SQL and vector/embedding tool operations.

MCP MariaDB Server