Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mariadb--mcp/badge.svg)](/listings/mariadb--mcp)

HTML

<a href="/listings/mariadb--mcp"><img src="/api/listings/mariadb--mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. **Subject:** 📢 Deprecation Notice: MariaDB MCP Server is moving (Effective Nov 3, 2026)
  2. Hello everyone,
  3. We are consolidating our AI tooling and want to let you know that effective **November 3, 2026**, this repository (`mariadb/mcp`) is officially deprecated.
  4. Going forward, all development, updates, and releases for the MariaDB MCP Server will take place in the official MariaDB AI Plugins repository.
  5. **Where to go next:**
  6. 👉 [mariadb-corporation/ai-plugins](https://github.com/mariadb-corporation/ai-plugins)
  7. Thank you for your support here, and we look forward to seeing you over at the new repo!
  8. ---
  9. # MCP MariaDB Server
  10. 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.
  11. ---
  12. ## Table of Contents
  13. - [Overview](#overview)
  14. - [Core Components](#core-components)
  15. - [Available Tools](#available-tools)
  16. - [Embeddings & Vector Store](#embeddings--vector-store)
  17. - [Configuration & Environment Variables](#configuration--environment-variables)
  18. - [Security Considerations](#security-considerations)
  19. - [Installation & Setup](#installation--setup)
  20. - [Usage Examples](#usage-examples)
  21. - [Integration - Claude desktop/Cursor/Windsurf](#integration---claude-desktopcursorwindsurf)
  22. - [Logging](#logging)
  23. - [Testing](#testing)
  24. ---
  25. ## Overview
  26. The MCP MariaDB Server exposes a set of tools for interacting with MariaDB databases and vector stores via a standardized protocol. It supports:
  27. - Listing databases and tables
  28. - Retrieving table schemas
  29. - Executing safe, read-only SQL queries
  30. - Creating and managing vector stores for embedding-based search
  31. - Integrating with embedding providers (currently OpenAI, Gemini, and HuggingFace) (optional)
  32. ---
  33. ## Core Components
  34. - **server.py**: Main MCP server logic and tool definitions.
  35. - **config.py**: Loads configuration from environment and `.env` files.
  36. - **embeddings.py**: Handles embedding service integration (OpenAI).
  37. - **tests/**: Manual and automated test documentation and scripts.
  38. ---
  39. ## Available Tools
  40. ### Standard Database Tools
  41. - **list_databases**
  42. - Lists all accessible databases.
  43. - Parameters: _None_
  44. - **list_tables**
  45. - Lists all tables in a specified database.
  46. - Parameters: `database_name` (string, required)
  47. - **get_table_schema**
  48. - Retrieves schema for a table (columns, types, keys, etc.).
  49. - Parameters: `database_name` (string, required), `table_name` (string, required)
  50. - **get_table_schema_with_relations**
  51. - Retrieves schema with foreign key relations for a table.
  52. - Parameters: `database_name` (string, required), `table_name` (string, required)
  53. - **execute_sql**
  54. - Executes a read-only SQL query (`SELECT`, `SHOW`, `DESCRIBE`).
  55. - Parameters: `sql_query` (string, required), `database_name` (string, optional), `parameters` (list, optional)
  56. - _Note: Enforces read-only mode if `MCP_READ_ONLY` is enabled._
  57. - **create_database**
  58. - Creates a new database if it doesn't exist.
  59. - Parameters: `database_name` (string, required)
  60. ### Vector Store & Embedding Tools (optional)
  61. **Note**: These tools are only available when `EMBEDDING_PROVIDER` is configured. If no embedding provider is set, these tools will be disabled.
  62. - **create_vector_store**
  63. - Creates a new vector store (table) for embeddings.
  64. - Parameters: `database_name`, `vector_store_name`, `model_name` (optional), `distance_function` (optional, default: cosine)
  65. - **delete_vector_store**
  66. - Deletes a vector store (table).
  67. - Parameters: `database_name`, `vector_store_name`
  68. - **list_vector_stores**
  69. - Lists all vector stores in a database.
  70. - Parameters: `database_name`
  71. - **insert_docs_vector_store**
  72. - Batch inserts documents (and optional metadata) into a vector store.
  73. - Parameters: `database_name`, `vector_store_name`, `documents` (list of strings), `metadata` (optional list of dicts)
  74. - **search_vector_store**
  75. - Performs semantic search for similar documents using embeddings.
  76. - Parameters: `database_name`, `vector_store_name`, `user_query` (string), `k` (optional, default: 7)
  77. ---
  78. ## Embeddings & Vector Store
  79. ### Overview
  80. 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.
  81. ### Supported Providers
  82. - **OpenAI**
  83. - **Gemini**
  84. - **Open models from Huggingface**
  85. ### Configuration
  86. - `EMBEDDING_PROVIDER`: Set to `openai`, `gemini`, `huggingface`, or leave unset to disable
  87. - `OPENAI_API_KEY`: Required if using OpenAI embeddings
  88. - `GEMINI_API_KEY`: Required if using Gemini embeddings
  89. - `HF_MODEL`: Required if using HuggingFace embeddings (e.g., "intfloat/multilingual-e5-large-instruct" or "BAAI/bge-m3")
  90. ### Model Selection
  91. - Default and allowed models are configurable in code (`DEFAULT_OPENAI_MODEL`, `ALLOWED_OPENAI_MODELS`)
  92. - Model can be selected per request or defaults to the configured model
  93. ### Vector Store Schema
  94. A vector store table has the following columns:
  95. - `id`: Auto-increment primary key
  96. - `document`: Text of the document
  97. - `embedding`: VECTOR type (indexed for similarity search)
  98. - `metadata`: JSON (optional metadata)
  99. ---
  100. ## Configuration & Environment Variables
  101. All configuration is via environment variables (typically set in a `.env` file):
  102. | Variable | Description | Required | Default |
  103. |------------------------|--------------------------------------------------------|----------|--------------|
  104. | `DB_HOST` | MariaDB host address | Yes | `localhost` |
  105. | `DB_PORT` | MariaDB port | No | `3306` |
  106. | `DB_USER` | MariaDB username | Yes | |
  107. | `DB_PASSWORD` | MariaDB password | Yes | |
  108. | `DB_NAME` | Default database (optional; can be set per query) | No | |
  109. | `DB_CHARSET` | Character set for database connection (e.g., `cp1251`) | No | MariaDB default |
  110. | `DB_SSL` | Enable SSL/TLS for database connection (`true`/`false`) | No | `false` |
  111. | `DB_SSL_CA` | Path to CA certificate file for SSL verification | No | |
  112. | `DB_SSL_CERT` | Path to client certificate file for SSL authentication | No | |
  113. | `DB_SSL_KEY` | Path to client private key file for SSL authentication | No | |
  114. | `DB_SSL_VERIFY_CERT` | Verify server certificate (`true`/`false`) | No | `true` |
  115. | `DB_SSL_VERIFY_IDENTITY` | Verify server hostname identity (`true`/`false`) | No | `false` |
  116. | `MCP_READ_ONLY` | Enforce read-only SQL mode (`true`/`false`) | No | `true` |
  117. | `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` |
  118. | `MCP_MAX_POOL_SIZE` | Max DB connection pool size | No | `10` |
  119. | `EMBEDDING_PROVIDER` | Embedding provider (`openai`/`gemini`/`huggingface`) | No |`None`(Disabled)|
  120. | `OPENAI_API_KEY` | API key for OpenAI embeddings | Yes (if EMBEDDING_PROVIDER=openai) | |
  121. | `GEMINI_API_KEY` | API key for Gemini embeddings | Yes (if EMBEDDING_PROVIDER=gemini) | |
  122. | `HF_MODEL` | Open models from Huggingface | Yes (if EMBEDDING_PROVIDER=huggingface) | |
  123. | `ALLOWED_ORIGINS` | Comma-separated list of allowed origins | No | Long list of allowed origins corresponding to local use of the server |
  124. | `ALLOWED_HOSTS` | Comma-separated list of allowed hosts | No | `localhost,127.0.0.1` |
  125. 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.
  126. #### Example `.env` file
  127. **With Embedding Support (OpenAI):**
  128. ```dotenv
  129. DB_HOST=localhost
  130. DB_USER=your_db_user
  131. DB_PASSWORD=your_db_password
  132. DB_PORT=3306
  133. DB_NAME=your_default_database
  134. MCP_READ_ONLY=true
  135. MCP_MAX_POOL_SIZE=10
  136. EMBEDDING_PROVIDER=openai
  137. OPENAI_API_KEY=sk-...
  138. GEMINI_API_KEY=AI...
  139. HF_MODEL="BAAI/bge-m3"
  140. ```
  141. **Without Embedding Support:**
  142. ```dotenv
  143. DB_HOST=localhost
  144. DB_USER=your_db_user
  145. DB_PASSWORD=your_db_password
  146. DB_PORT=3306
  147. DB_NAME=your_default_database
  148. MCP_READ_ONLY=true
  149. MCP_MAX_POOL_SIZE=10
  150. ```
  151. **With SSL/TLS Enabled:**
  152. ```dotenv
  153. DB_HOST=your-remote-host.com
  154. DB_USER=your_db_user
  155. DB_PASSWORD=your_db_password
  156. DB_PORT=3306
  157. DB_NAME=your_default_database
  158. # Enable SSL
  159. DB_SSL=true
  160. DB_SSL_CA=~/.mysql/ca-cert.pem
  161. DB_SSL_CERT=~/.mysql/client-cert.pem
  162. DB_SSL_KEY=~/.mysql/client-key.pem
  163. DB_SSL_VERIFY_CERT=true
  164. DB_SSL_VERIFY_IDENTITY=false
  165. MCP_READ_ONLY=true
  166. MCP_MAX_POOL_SIZE=10
  167. ```
  168. **Note on SSL Configuration:**
  169. - All SSL certificate paths support `~` for home directory expansion
  170. - `DB_SSL_CA` is used to verify the server's certificate
  171. - `DB_SSL_CERT` and `DB_SSL_KEY` are used for client certificate authentication (mutual TLS)
  172. - Set `DB_SSL_VERIFY_CERT=false` only for testing with self-signed certificates
  173. - Set `DB_SSL_VERIFY_IDENTITY=true` to enable strict hostname verification
  174. **Example Authentication Configuration:**
  175. 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.
  176. ```dotenv
  177. # GitHub OAuth
  178. export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
  179. export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..."
  180. export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="github_pat_..."
  181. # Google OAuth
  182. export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
  183. export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="123456.apps.googleusercontent.com"
  184. export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="GOCSPX-..."
  185. ```
  186. ### Database User Privileges - **IMPORTANT**
  187. **⚠️ 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.
  188. 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.
  189. ---
  190. ## Installation & Setup
  191. ### Requirements
  192. - **Python 3.11** (see `.python-version`)
  193. - **uv** (dependency manager; [install instructions](https://github.com/astral-sh/uv))
  194. - MariaDB server (local or remote)
  195. ### Steps
  196. 1. **Clone the repository**
  197. 2. **Install `uv`** (if not already):
  198. ```bash
  199. pip install uv
  200. ```
  201. 3. **Install dependencies**
  202. ```bash
  203. uv lock
  204. uv sync
  205. ```
  206. 4. **Create `.env`** in the project root (see [Configuration](#configuration--environment-variables))
  207. 5. **Run the server**
  208. **Standard Input/Output (default):**
  209. ```bash
  210. uv run server.py
  211. ```
  212. **SSE Transport:**
  213. ```bash
  214. uv run server.py --transport sse --host 127.0.0.1 --port 9001
  215. ```
  216. **HTTP Transport (streamable HTTP):**
  217. ```bash
  218. uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp
  219. ```
  220. ---
  221. ## Usage Examples
  222. ### Standard SQL Query
  223. ```python
  224. {
  225. "tool": "execute_sql",
  226. "parameters": {
  227. "database_name": "test_db",
  228. "sql_query": "SELECT * FROM users WHERE id = %s",
  229. "parameters": [123]
  230. }
  231. }
  232. ```
  233. ### Create Vector Store
  234. ```python
  235. {
  236. "tool": "create_vector_store",
  237. "parameters": {
  238. "database_name": "test_db",
  239. "vector_store_name": "my_vectors",
  240. "model_name": "text-embedding-3-small",
  241. "distance_function": "cosine"
  242. }
  243. }
  244. ```
  245. ### Insert Documents into Vector Store
  246. ```python
  247. {
  248. "tool": "insert_docs_vector_store",
  249. "parameters": {
  250. "database_name": "test_db",
  251. "vector_store_name": "my_vectors",
  252. "documents": ["Sample text 1", "Sample text 2"],
  253. "metadata": [{"source": "doc1"}, {"source": "doc2"}]
  254. }
  255. }
  256. ```
  257. ### Semantic Search
  258. ```python
  259. {
  260. "tool": "search_vector_store",
  261. "parameters": {
  262. "database_name": "test_db",
  263. "vector_store_name": "my_vectors",
  264. "user_query": "What is the capital of France?",
  265. "k": 5
  266. }
  267. }
  268. ```
  269. ---
  270. ## Integration - Claude desktop/Cursor/Windsurf/VSCode
  271. ### Option 1: Direct Command (stdio)
  272. ```json
  273. {
  274. "mcpServers": {
  275. "MariaDB_Server": {
  276. "command": "uv",
  277. "args": [
  278. "--directory",
  279. "path/to/mariadb-mcp-server/",
  280. "run",
  281. "server.py"
  282. ],
  283. "envFile": "path/to/mcp-server-mariadb-vector/.env"
  284. }
  285. }
  286. }
  287. ```
  288. ### Option 2: SSE Transport
  289. ```json
  290. {
  291. "servers": {
  292. "mariadb-mcp-server": {
  293. "url": "http://{host}:9001/sse",
  294. "type": "sse"
  295. }
  296. }
  297. }
  298. ```
  299. ### Option 3: HTTP Transport
  300. ```json
  301. {
  302. "servers": {
  303. "mariadb-mcp-server": {
  304. "url": "http://{host}:9001/mcp",
  305. "type": "streamable-http"
  306. }
  307. }
  308. }
  309. ```
  310. ### Option 4: Docker container
  311. ```json
  312. {
  313. "servers": {
  314. "mariadb-mcp-server": {
  315. "command": "docker",
  316. "args": [
  317. "run",
  318. "-i",
  319. "--rm",
  320. "-p",
  321. "9001:9001",
  322. "-e",
  323. "DB_HOST=",
  324. "-e",
  325. "DB_PORT=",
  326. "-e",
  327. "DB_USER=",
  328. "-e",
  329. "DB_PASSWORD=",
  330. "-e",
  331. "DB_NAME=",
  332. "mariadb-mcp-server",
  333. "python",
  334. "src/server.py",
  335. "--host",
  336. "0.0.0.0",
  337. "--transport",
  338. "stdio"
  339. ]
  340. }
  341. }
  342. }
  343. ```
  344. ---
  345. ## Logging
  346. - Logs are written to `logs/mcp_server.log` by default.
  347. - Log messages include tool calls, configuration issues, embedding errors, and client requests.
  348. - Log level and output can be adjusted in the code (see `config.py` and logger setup).
  349. ---
  350. ## Testing
  351. - Tests are located in the `src/tests/` directory.
  352. - See `src/tests/README.md` for an overview.
  353. - Tests cover both standard SQL and vector/embedding tool operations.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.