How to Set Up a MariaDB MCP Server for Claude, Cursor & Codex

This post was written by an engineer at QueryPlane. QueryPlane is an app builder for your database: bring your own postgres db and you can create interactive applications to share with other developers, coworkers or even your customers. If you’re interested in trying it out, get started here.

---

MCP (Model Context Protocol) lets AI tools like Claude Desktop, Claude Code, Cursor, and Codex connect directly to your MariaDB database. Instead of copy-pasting schemas and query results into chat, the AI can inspect your tables, run queries, and analyze your data autonomously.

In this post, we’ll cover:

• What is MCP — How the protocol works
• Best MariaDB MCP servers — Official and multi-database options
• Setup guides — Step-by-step for Claude Desktop and Claude Code
• Security considerations — Keeping your database safe

What is MCP?

The Model Context Protocol is an open standard created by Anthropic that lets AI applications connect to external data sources and tools. Think of it as a USB-C port for AI — a standardized way for any AI client to talk to any data source.

For databases, MCP servers expose tools like list_tables, describe_table, and execute_sql that AI agents can call — letting Claude or Codex explore your schema and query your data without manual context.

Best MariaDB MCP Servers

1. Official MariaDB MCP

MariaDB/mcp (~166 stars) is maintained by MariaDB and is the recommended option.

Features:

• Schema inspection and SQL execution
• Vector/embedding-based search (requires configuring an embedding provider like OpenAI or HuggingFace)
• MariaDB-native connection handling
• Read-only mode via MCP_READ_ONLY env var (defaults to true)

Claude Desktop config:

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mariadb-mcp-server",
        "run", "server.py"
      ],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "password",
        "DB_NAME": "mydb"
      }
    }
  }
}

2. DBHub (Bytebase)

DBHub (~2,600 stars) supports MariaDB alongside PostgreSQL, MySQL, SQL Server, and SQLite.

Claude Code setup:

claude mcp add --transport stdio dbhub -- \
  npx @bytebase/dbhub@latest \
  --transport stdio \
  --dsn "mariadb://user:pass@localhost:3306/mydb"

3. MCP-Alchemy

mcp-alchemy (~400 stars) uses SQLAlchemy under the hood and supports MariaDB alongside every other database SQLAlchemy supports.

4. MySQL MCP Servers

Since MariaDB is MySQL wire-compatible, most MySQL MCP servers also work with MariaDB:

• benborla/mcp-server-mysql (~1,570 stars)
• designcomputer/mysql_mcp_server (~1,230 stars)

Which MariaDB MCP Server Should You Use?

Server	Stars	Official?	Vector search	Multi-database
MariaDB MCP	~166	Yes	Yes	No
DBHub	~2,600	Community	No	Yes
MCP-Alchemy	~400	Community	No	Yes
MySQL MCP servers	~1,570	Community	No	No

For most developers, use the official MariaDB MCP server — it has the deepest MariaDB integration including vector search support. If you work with multiple databases, use DBHub.

Security Considerations

Connecting an AI agent to MariaDB carries risk. Follow these practices:

• Use a read-only database user — create a dedicated user with SELECT-only permissions
• Connect to a replica — point MCP at a read replica, not your primary
• Limit schema access — restrict the user to specific databases
• Don’t expose credentials in configs — use environment variables
• Enable the general query log — track what the AI runs

-- Create a read-only user for MCP
CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'secure_password';
GRANT SELECT ON mydb.* TO 'mcp_reader'@'%';
FLUSH PRIVILEGES;

Using MCP with QueryPlane

If you want the benefits of AI-powered database access without managing MCP servers, QueryPlane provides this out of the box. Connect your MariaDB database and use AI to generate queries, explore schemas, and build dashboards — all from your browser with built-in access controls.

FAQ

What is a MariaDB MCP server?

A MariaDB MCP server is a process that implements the Model Context Protocol to let AI tools (Claude, Cursor, Codex, Windsurf) connect to your MariaDB database. It exposes tools for listing tables, describing schemas, and running SQL queries.

How do I connect Claude to MariaDB?

Install the official MariaDB MCP server or a MySQL-compatible server, then add it to your Claude Desktop config or use claude mcp add in Claude Code.

Can I use a MySQL MCP server with MariaDB?

Yes. MariaDB is MySQL wire-compatible, so most MySQL MCP servers work with MariaDB using a standard connection string.

Does MariaDB MCP support vector search?

Yes, but it requires configuring an external embedding provider (OpenAI, Gemini, or HuggingFace) via the EMBEDDING_PROVIDER env var. Without this configuration, vector search tools are disabled.

Wrapping up

MariaDB has an official MCP server with vector search support, and its MySQL compatibility means many additional MCP servers work out of the box. Start with a read-only setup and see how AI-powered database access fits your workflow.