MCP MariaDB Server

What is MCP MariaDB Server about?

MCP MariaDB Server exposes a set of tools that allow callers to list databases, inspect table schemas, run read‑only SQL queries, and optionally create and query vector stores powered by embedding providers such as OpenAI, Gemini, or HuggingFace. The server follows the Model Context Protocol, making it easy to integrate with AI assistants and other LLM‑driven workflows.

How to use MCP MariaDB Server?

1. Clone the repository

   git clone https://github.com/MariaDB/mcp.git
   cd mcp
   

2. Install the Python dependencies (requires Python 3.11 and uv)

   pip install uv
   uv pip compile pyproject.toml -o uv.lock
   uv pip sync uv.lock
   

3. Create a .env file at the project root with the required connection parameters and, if needed, embedding credentials (see the "Configuration & Environment Variables" table in the README).
4. Start the server

   python server.py
   

   The server will listen for MCP requests (default SSE endpoint http://localhost:9001/sse).
5. Invoke tools by sending JSON payloads that specify the tool name and its parameters, e.g., execute_sql, create_vector_store, search_vector_store, etc.

Key features of MCP MariaDB Server

• Standard database operations: list databases/tables, fetch schema, execute safe read‑only SQL queries.
• Read‑only enforcement via MCP_READ_ONLY flag.
• Dynamic database selection per request.
• Optional vector store creation and management for semantic search.
• Embedding integration with OpenAI, Gemini, and HuggingFace models.
• Configurable distance functions (cosine, Euclidean, etc.) for similarity search.
• Environment‑driven configuration via .env file.
• Logging to logs/mcp_server.log with detailed request and error information.
• Test suite covering both SQL and vector‑store tools.

Use cases of MCP MariaDB Server

• AI‑augmented data retrieval: An LLM can query relational data and perform semantic similarity searches in a single workflow.
• Knowledge base construction: Store document embeddings alongside relational metadata for fast context‑aware look‑ups.
• Data access control: Enforce read‑only mode for external agents while still allowing schema exploration.
• Rapid prototyping of AI assistants that need both structured query results and unstructured text search.
• Multi‑model embedding experiments by switching EMBEDDING_PROVIDER and model names without code changes.

FAQ from MCP MariaDB Server

Q: Do I need an embedding provider to use the server? A: No. Vector‑store tools are disabled unless EMBEDDING_PROVIDER is set. All standard SQL tools work independently.

Q: Can I run write queries (INSERT/UPDATE)? A: The server only exposes read‑only SQL (SELECT, SHOW, DESCRIBE). Write operations must be performed outside the MCP interface.

Q: How is the vector similarity computed? A: The server stores embeddings in a MariaDB VECTOR column and uses the configured distance_function (default: cosine) for nearest‑neighbor search.

Q: Which Python version is required? A: Python 3.11 as defined in .python-version.

Q: Where are logs stored? A: By default to logs/mcp_server.log. Log level can be adjusted in config.py.

Q: How do I change the server port? A: The port is hard‑coded in server.py or can be overridden by editing the launch command; there is no dedicated environment variable.

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
• 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)

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

---

Installation & Setup

Requirements

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

Steps

1. Clone the repository
2. Install uv (if not already):

   pip install uv
   

3. Install dependencies

   uv pip compile pyproject.toml -o uv.lock
   

   uv pip sync uv.lock
   

4. Create .env in the project root (see Configuration)
5. Run the server

   python server.py
   

   Adjust entry point if needed (e.g., main.py)

---

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

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

or If already running MCP server

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

---

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.