mariadb-mcp

yawlhead91/mariadb-mcp

3.2

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.

Tools
5
Resources
0
Prompts
0

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:

  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:

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