MariaDB
An interface for managing and querying MariaDB databases that supports standard SQL operations alongside advanced vector and embedding-based search capabilities. It enables AI assistants to seamlessly integrate relational and vector data workflows th
What is MariaDB?
MariaDB is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to interface for managing and querying mariadb databases that supports standard sql operations alongside advanced vector and embedding-based search capabilities. it enables ai assistants to seamlessly in...
An interface for managing and querying MariaDB databases that supports standard SQL operations alongside advanced vector and embedding-based search capabilities. It enables AI assistants to seamlessly integrate relational and vector data workflows th
This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- An interface for managing and querying MariaDB databases tha
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mcp-mariadb-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use MariaDB
The MCP MariaDB Server provides AI assistants with a secure, read-safe interface for querying and managing MariaDB databases, combining standard SQL operations with optional vector embedding search capabilities. It supports listing databases and table schemas, executing parameterized read-only queries, creating databases, and performing semantic similarity searches via configurable embedding providers (OpenAI, Gemini, or HuggingFace). Data teams and developers use it to let Claude explore database schemas, answer natural language questions about relational data, and combine SQL queries with vector-based document retrieval in a single workflow.
Prerequisites
- Python 3.10 or later with the uv package manager
- A running MariaDB instance with connection credentials (host, user, password, database name)
- Optional: An OpenAI, Google Gemini, or HuggingFace API key if you want vector embedding and semantic search features
- An MCP-compatible client such as Claude Desktop
Clone the repository and install dependencies
Clone the MariaDB MCP repository and install its Python dependencies using uv.
git clone https://github.com/MariaDB/mcp.git
cd mcp
uv lock && uv syncCreate a .env configuration file
Create a .env file in the project root with your MariaDB connection details and optional settings. MCP_READ_ONLY defaults to true for safety.
DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10
# Optional: for vector/embedding features
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...Test the server from the command line
Run the server directly to verify it can connect to your MariaDB instance before configuring your MCP client.
uv run server.pyAdd the server to your MCP client configuration
Register the MariaDB MCP server in your Claude Desktop config using the uv run command and pointing to your .env file.
Apply secure database permissions
For production use, create a dedicated MariaDB user with only SELECT privileges. MCP_READ_ONLY provides best-effort protection but is not a substitute for proper database-level access control.
-- In MariaDB
CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
FLUSH PRIVILEGES;MariaDB Examples
Client configuration
Add the MariaDB MCP server to Claude Desktop using uv to run server.py. Point envFile to your .env file containing database credentials.
{
"mcpServers": {
"MariaDB_Server": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp",
"run",
"server.py"
],
"env": {
"DB_HOST": "localhost",
"DB_USER": "mcp_user",
"DB_PASSWORD": "your_password",
"DB_PORT": "3306",
"MCP_READ_ONLY": "true"
}
}
}
}Prompts to try
Ask Claude to explore your MariaDB databases and run queries using natural language.
- "List all databases available and show the schema for the orders table"
- "How many customers signed up in the last 30 days?"
- "Find the top 10 products by revenue this quarter using a SQL query"
- "Create a vector store from the product descriptions and search for items similar to 'wireless noise-cancelling headphones'"
- "What foreign key relationships exist in the users database schema?"Troubleshooting MariaDB
Connection refused when the server tries to reach MariaDB
Verify DB_HOST, DB_PORT, DB_USER, and DB_PASSWORD in your .env file. Ensure MariaDB is running with `systemctl status mariadb` (Linux) or the MariaDB service panel. Check that the user has permission to connect from the server's host.
MCP_READ_ONLY is set but the server still allows write queries
MCP_READ_ONLY is a best-effort guard, not a hard database-level constraint. For guaranteed read-only access, grant only SELECT privileges to the database user as shown in the setup steps.
Embedding/vector features return an error about missing provider
Set EMBEDDING_PROVIDER to openai, gemini, or huggingface in your .env file and provide the corresponding API key (OPENAI_API_KEY, GEMINI_API_KEY, or HUGGINGFACE_API_KEY). Vector features are disabled if EMBEDDING_PROVIDER is not set.
Frequently Asked Questions about MariaDB
What is MariaDB?
MariaDB is a Model Context Protocol (MCP) server that interface for managing and querying mariadb databases that supports standard sql operations alongside advanced vector and embedding-based search capabilities. it enables ai assistants to seamlessly integrate relational and vector data workflows th It connects AI assistants to external tools and data sources through a standardized interface.
How do I install MariaDB?
Follow the installation instructions on the MariaDB GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with MariaDB?
MariaDB works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is MariaDB free to use?
Yes, MariaDB is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
MariaDB Alternatives — Similar Databases Servers
Looking for alternatives to MariaDB? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.
Excelize
★ 20.6kGo language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets
MCP Toolbox for Databases
★ 15.3kOpen source MCP server specializing in easy, fast, and secure tools for Databases.
DBHub
★ 2.8kA universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
Tabularis
★ 2.1kA lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.
Postgres AI Guide
★ 1.7kMCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Anyquery
★ 1.7k🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.
Browse More Databases MCP Servers
Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up MariaDB in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use MariaDB?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.