MariaDB/mcp

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
- Security Considerations
- 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