yawlhead91/mariadb-mcp
If you are the rightful owner of mariadb-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The MariaDB MCP Server is a Model Context Protocol server designed for managing MariaDB database operations, compatible with Claude Code and other MCP clients.
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
Installation
Prerequisites
- Python 3.10 or higher
- MariaDB server running
uv
package 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 credentials
Configuration
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=INFO
Local 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.py
Connect 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 mariadb
-
Test connection manually:
mysql -h localhost -u root -p
-
Check 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.py
Logging
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.log
with automatic rotation- Maximum 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 debugging
Or 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