Skip to main content
Glama
MariaDB MCP Server

MariaDB MCP Server

by yawlhead91

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

  • 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

Available Tools

5 tools
execute_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

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides 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.
      4
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables interaction with MariaDB/MySQL databases via MCP, supporting read-only mode, SQL execution, and schema inspection.
      6
      MIT