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

Configuration

Environment Variables

Configure your MariaDB connection using these environment variables:

Local Development

For local testing, create a .env file in the project root with your database credentials.

Usage

Command Line

Run the server directly:

Connect with Claude Code in another terminal:

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)

Option B: Direct environment variables

Note: When both env and envFile are specified, env variables take precedence.

After configuration:

1. Restart Claude Code

2. Verify "MariaDB_Server" appears in your MCP server list

3. 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 name

• database (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 execute

• database (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

1. Verify MariaDB is running:

   sudo systemctl status mariadb # or on macOS with Homebrew: brew services list | grep mariadb

2. Test connection manually:

   mysql -h localhost -u root -p

3. Check firewall settings for remote connections

Permission Issues

Ensure your MariaDB user has SELECT permissions:

Debug Mode

For development debugging:

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

Or in Claude Code configuration:

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