MariaDB MCP Server
The MariaDB MCP Server provides read-only access to MariaDB databases through the Model Context Protocol, enabling safe database exploration and querying.
Core Operations:
List Databases - Retrieve all accessible databases on the MariaDB server
List Tables - View tables within a specific or current database
Get Table Schema - Obtain detailed structure, columns, data types, constraints, and statistics for tables
Execute SQL Queries - Run read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN) with optional database specification
Reload Configuration - Update connection settings from environment variables and .env files without restarting
Security Features:
Strictly enforces read-only access, blocking INSERT, UPDATE, DELETE, and DDL statements
Supports secure configuration via environment variables or .env files
Connection pooling for efficient resource management
Comprehensive logging with configurable verbosity levels (DEBUG, INFO, WARNING, ERROR, CRITICAL) and automatic log rotation
Use Cases:
Database exploration and documentation
Schema analysis and data modeling
Query testing and development
Integration with MCP clients like Claude Code for AI-assisted database operations
Provides tools for database operations including listing databases and tables, retrieving table schemas, and executing read-only SQL queries (SELECT, SHOW, DESCRIBE, EXPLAIN) against MariaDB databases.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MariaDB MCP Server show me the schema for the customers table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MariaDB MCP Server
A Model Context Protocol (MCP) server for MariaDB database operations, compatible with Claude Code and other MCP clients.
Features
This MCP server provides these standard database tools:
list_databases: List all accessible databases
list_tables: List tables in a database
get_table_schema: Get detailed table schema and statistics
execute_sql: Execute read-only SQL queries (SELECT, SHOW, DESCRIBE, EXPLAIN)
reload_config: Reload configuration without restarting
Related MCP server: MySQL MCP Server
Installation
Prerequisites
Python 3.10 or higher
MariaDB server running
uvpackage manager
Quick Setup
# Clone/download this repository
cd mariadb-mcp
# Install dependencies
uv sync
# Configure database connection
cp .env.example .env
# Edit .env with your MariaDB credentialsConfiguration
Environment Variables
Configure your MariaDB connection using these environment variables:
MARIADB_HOST=localhost
MARIADB_PORT=3306
MARIADB_USER=root
MARIADB_PASSWORD=your_password_here
MARIADB_DATABASE=mysql
# Optional: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_LEVEL=INFOLocal Development
For local testing, create a .env file in the project root with your database credentials.
Usage
Command Line
Run the server directly:
uv run python src/mariadb_mcp/server.pyConnect with Claude Code in another terminal:
claude-code --mcp-server "uv run python src/mariadb_mcp/server.py"Adding to Claude Code Permanently
To add this server to your Claude Code MCP server list:
Manual Configuration
Add to your Claude Code configuration file:
Option A: Using environment file (recommended)
{
"mcpServers": {
"MariaDB_Server": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mariadb-mcp/",
"run",
"python",
"src/mariadb_mcp/server.py"
],
"envFile": "/absolute/path/to/mariadb-mcp/.env"
}
}
}Option B: Direct environment variables
{
"mcpServers": {
"MariaDB_Server": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/mariadb-mcp/",
"run",
"python",
"src/mariadb_mcp/server.py"
],
"env": {
"MARIADB_HOST": "localhost",
"MARIADB_PORT": "3306",
"MARIADB_USER": "root",
"MARIADB_PASSWORD": "your_password_here",
"MARIADB_DATABASE": "mysql"
}
}
}
}Note: When both env and envFile are specified, env variables take precedence.
After configuration:
Restart Claude Code
Verify "MariaDB_Server" appears in your MCP server list
Test with: "List all databases"
Available Tools
reload_config()
Reload database configuration without restarting the server.
Example: "Reload the database configuration"
list_databases()
List all databases you have access to.
Example: "List all available databases"
list_tables(database: Optional[str])
List tables in a database.
Parameters:
database(optional): Database name
Examples:
"List tables in the current database"
"List tables in the 'myapp' database"
get_table_schema(table_name: str, database: Optional[str])
Get detailed schema information for a table.
Parameters:
table_name: Table namedatabase(optional): Database name
Examples:
"Show schema for the 'users' table"
"Get table structure for 'orders' in the 'ecommerce' database"
execute_sql(query: str, database: Optional[str])
Execute read-only SQL queries.
Parameters:
query: SQL query to executedatabase(optional): Database to use
Examples:
"Execute: SELECT * FROM users LIMIT 10"
"Run query: SHOW CREATE TABLE products"
"Execute in 'analytics' database: SELECT COUNT(*) FROM events"
Security
Read-only operations: Only SELECT, SHOW, DESCRIBE, EXPLAIN allowed
No data modification: INSERT, UPDATE, DELETE, DDL statements blocked
Connection pooling: Efficient resource management
Comprehensive logging: Full error reporting
Troubleshooting
Connection Issues
Verify MariaDB is running:
sudo systemctl status mariadb # or on macOS with Homebrew: brew services list | grep mariadbTest connection manually:
mysql -h localhost -u root -pCheck firewall settings for remote connections
Permission Issues
Ensure your MariaDB user has SELECT permissions:
GRANT SELECT ON *.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;Debug Mode
For development debugging:
uv run mcp dev src/mariadb_mcp/server.pyLogging
The MariaDB MCP server includes comprehensive logging for monitoring and debugging:
Log Locations
Console: Real-time logs displayed in the terminal
Log Files: Stored in
logs/mariadb_mcp.logwith automatic rotationMaximum file size: 10MB
Backup files: 5 (mariadb_mcp.log.1, mariadb_mcp.log.2, etc.)
Log Levels
Set the LOG_LEVEL environment variable to control log verbosity:
DEBUG: Detailed information for diagnosing problems (shows SQL queries)
INFO: General information about server operations (default)
WARNING: Something unexpected happened but the server continues
ERROR: An error occurred but the server continues
CRITICAL: A serious error occurred
Example Logging Configuration
# In your .env file
LOG_LEVEL=DEBUG # For detailed debuggingOr in Claude Code configuration:
"env": {
"MARIADB_HOST": "localhost",
"MARIADB_USER": "root",
"MARIADB_PASSWORD": "dev",
"LOG_LEVEL": "DEBUG"
}Log Contents
Logs include:
Server startup/shutdown events
Database connection status
Tool function calls and results
SQL query execution (DEBUG level)
Error messages with stack traces
Configuration changes
License
MIT License
Available Tools
5 toolsexecute_sqlB
Execute a read-only SQL query and return results.
Inputs: query (required), database. Returns: result
get_table_schemaB
Get the schema/structure of a specific table.
Inputs: table_name (required), database. Returns: result
list_databasesB
List all accessible databases in the MariaDB server.
Inputs: no named parameters. Returns: result
list_tablesB
List all tables in a specific database.
Inputs: database. Returns: result
reload_configB
Reload configuration from environment variables and .env file.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose with no overlap: execute_sql for queries, get_table_schema for metadata, list_databases and list_tables for discovery, and reload_config for server management. An agent can easily distinguish between them without confusion.
All tools follow a consistent verb_noun pattern using snake_case (e.g., execute_sql, get_table_schema). The naming is predictable and readable throughout the set, with no deviations in style.
With 5 tools, the count is reasonable and well-scoped for a database server, covering core operations like querying, schema inspection, and listing. It's slightly lean but functional, with no obvious bloat or thinness.
The tools cover read operations and metadata well, but there are notable gaps for a full database lifecycle: no create/update/delete operations for databases, tables, or data. This limits agents to read-only and discovery tasks, which may cause failures in broader workflows.
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Read your Iceberg tables hosted in Europe: find tables, run read-only SQL, view photos.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides secure, read-only access to MariaDB/MySQL databases, allowing users to list databases, explore table schemas, and execute SQL queries with built-in security measures.44MIT
- FlicenseNot gradedqualityDmaintenanceEnables safe interaction with MySQL databases through SELECT queries, table structure inspection, and database schema exploration. Provides read-only access to query data and examine database metadata.1-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with MariaDB databases through schema exploration, query execution, and database statistics. Includes security features like read-only mode, parameterized queries, and connection pooling with support for both JSON and Markdown output formats.-
- AlicenseAqualityCmaintenanceEnables interaction with MariaDB/MySQL databases via MCP, supporting read-only mode, SQL execution, and schema inspection.6MIT