mcp
MariaDB MCP (Model Context Protocol) server implementation
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/mariadb--mcp)HTML
<a href="/listings/mariadb--mcp"><img src="/api/listings/mariadb--mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requirements
- **Python 3.11** (see `.python-version`) - **uv** (dependency manager; [install instructions](https://github.com/astral-sh/uv)) - MariaDB server (local or remote)
Steps
1. **Clone the repository** 2. **Install `uv`** (if not already):
pip install uv
3. **Install dependencies**
uv lock uv sync
4. **Create `.env`** in the project root (see [Configuration](#configuration--environment-variables)) 5. **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
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 447 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- **Subject:** 📢 Deprecation Notice: MariaDB MCP Server is moving (Effective Nov 3, 2026)
- Hello everyone,
- We are consolidating our AI tooling and want to let you know that effective **November 3, 2026**, this repository (`mariadb/mcp`) is officially deprecated.
- Going forward, all development, updates, and releases for the MariaDB MCP Server will take place in the official MariaDB AI Plugins repository.
- **Where to go next:**
- 👉 [mariadb-corporation/ai-plugins](https://github.com/mariadb-corporation/ai-plugins)
- Thank you for your support here, and we look forward to seeing you over at the new repo!
- ---
- # MCP MariaDB Server
- 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.
- ---
- ## Table of Contents
- - [Overview](#overview)
- - [Core Components](#core-components)
- - [Available Tools](#available-tools)
- - [Embeddings & Vector Store](#embeddings--vector-store)
- - [Configuration & Environment Variables](#configuration--environment-variables)
- - [Security Considerations](#security-considerations)
- - [Installation & Setup](#installation--setup)
- - [Usage Examples](#usage-examples)
- - [Integration - Claude desktop/Cursor/Windsurf](#integration---claude-desktopcursorwindsurf)
- - [Logging](#logging)
- - [Testing](#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 |
- | `DB_SSL` | Enable SSL/TLS for database connection (`true`/`false`) | No | `false` |
- | `DB_SSL_CA` | Path to CA certificate file for SSL verification | No | |
- | `DB_SSL_CERT` | Path to client certificate file for SSL authentication | No | |
- | `DB_SSL_KEY` | Path to client private key file for SSL authentication | No | |
- | `DB_SSL_VERIFY_CERT` | Verify server certificate (`true`/`false`) | No | `true` |
- | `DB_SSL_VERIFY_IDENTITY` | Verify server hostname identity (`true`/`false`) | No | `false` |
- | `MCP_READ_ONLY` | Enforce read-only SQL mode (`true`/`false`) | No | `true` |
- | `MCP_BLOCK_SENSITIVE_SHOW` | Block sensitive `SHOW` commands (`PROCESSLIST`, `GRANTS`, `VARIABLES`, `MASTER`/`REPLICA STATUS`, `BINARY LOGS`, etc.) that can leak cross-connection query text, credentials/privileges, or replication topology. Set independently of `MCP_READ_ONLY` (`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](https://gofastmcp.com/servers/auth/authentication#environment-configuration) for more information. We have provided an example configuration below.
- #### Example `.env` file
- **With Embedding Support (OpenAI):**
- ```dotenv
- 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:**
- ```dotenv
- 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
- ```
- **With SSL/TLS Enabled:**
- ```dotenv
- 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
- ```
- **Note on SSL Configuration:**
- - All SSL certificate paths support `~` for home directory expansion
- - `DB_SSL_CA` is used to verify the server's certificate
- - `DB_SSL_CERT` and `DB_SSL_KEY` are used for client certificate authentication (mutual TLS)
- - Set `DB_SSL_VERIFY_CERT=false` only for testing with self-signed certificates
- - Set `DB_SSL_VERIFY_IDENTITY=true` to 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.
- ```dotenv
- # 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-..."
- ```
- ### Database User Privileges - **IMPORTANT**
- **⚠️ 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.
- ---
- ## Installation & Setup
- ### Requirements
- - **Python 3.11** (see `.python-version`)
- - **uv** (dependency manager; [install instructions](https://github.com/astral-sh/uv))
- - MariaDB server (local or remote)
- ### Steps
- 1. **Clone the repository**
- 2. **Install `uv`** (if not already):
- ```bash
- pip install uv
- ```
- 3. **Install dependencies**
- ```bash
- uv lock
- uv sync
- ```
- 4. **Create `.env`** in the project root (see [Configuration](#configuration--environment-variables))
- 5. **Run the server**
- **Standard Input/Output (default):**
- ```bash
- uv run server.py
- ```
- **SSE Transport:**
- ```bash
- uv run server.py --transport sse --host 127.0.0.1 --port 9001
- ```
- **HTTP Transport (streamable HTTP):**
- ```bash
- uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp
- ```
- ---
- ## Usage Examples
- ### Standard SQL Query
- ```python
- {
- "tool": "execute_sql",
- "parameters": {
- "database_name": "test_db",
- "sql_query": "SELECT * FROM users WHERE id = %s",
- "parameters": [123]
- }
- }
- ```
- ### Create Vector Store
- ```python
- {
- "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
- ```python
- {
- "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
- ```python
- {
- "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)
- ```json
- {
- "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
- ```json
- {
- "servers": {
- "mariadb-mcp-server": {
- "url": "http://{host}:9001/sse",
- "type": "sse"
- }
- }
- }
- ```
- ### Option 3: HTTP Transport
- ```json
- {
- "servers": {
- "mariadb-mcp-server": {
- "url": "http://{host}:9001/mcp",
- "type": "streamable-http"
- }
- }
- }
- ```
- ### Option 4: Docker container
- ```json
- {
- "servers": {
- "mariadb-mcp-server": {
- "command": "docker",
- "args": [
- "run",
- "-i",
- "--rm",
- "-p",
- "9001:9001",
- "-e",
- "DB_HOST=",
- "-e",
- "DB_PORT=",
- "-e",
- "DB_USER=",
- "-e",
- "DB_PASSWORD=",
- "-e",
- "DB_NAME=",
- "mariadb-mcp-server",
- "python",
- "src/server.py",
- "--host",
- "0.0.0.0",
- "--transport",
- "stdio"
- ]
- }
- }
- }
- ```
- ---
- ## 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.