MariaDB MCP Server

How to use

You connect to the server from your MCP client by configuring it as a local MCP service. Once connected, you can explore databases and tables, inspect table schemas, and run queries. Use read-only mode to prevent writes, or enable write access if you need to modify data. Retrieve results in JSON for programmatic consumption or Markdown for human-readable reports. When dealing with large result sets, rely on pagination to fetch data in chunks and keep response times fast.

How to install

Prerequisites and core setup steps ensure you can run the MCP server locally and connect your client.

# Prerequisites
python3.8+
# MariaDB Connector/C is required for the MariaDB Python connector

# Install dependencies
pip install -r requirements.txt
# Or install packages individually
pip install mcp mariadb

Additional configuration and usage notes

Configure the server through environment variables to set up the database connection and behavior. Example variables include host, port, user, password, the default database, read-only mode, and connection pool size.

export MARIADB_HOST="localhost"           # Database server hostname
export MARIADB_PORT="3306"               # Database server port
export MARIADB_USER="your_username"      # Database username
export MARIADB_PASSWORD="your_password"  # Database password
export MARIADB_DATABASE=""               # Default database (optional)
export MARIADB_READ_ONLY="true"          # Set to "false" to allow write queries
export MARIADB_POOL_SIZE="5"             # Connection pool size (default: 5)

Claude Desktop configuration (stdio)

Use these settings to start the MCP server from the Claude Desktop client on your computer.

{
  "mcpServers": {
    "mariadb": {
      "command": "python",
      "args": ["/path/to/mariadb_mcp_server.py"],
      "env": {
        "MARIADB_HOST": "localhost",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your_username",
        "MARIADB_PASSWORD": "your_password",
        "MARIADB_DATABASE": "your_database",
        "MARIADB_READ_ONLY": "true"
      }
    }
  }
}

Alternative: Using uvx (stdio)

If you package and publish the server to PyPI, you can start it using uvx for easy updates.

{
  "mcpServers": {
    "mariadb": {
      "command": "uvx",
      "args": ["mariadb-mcp-server"],
      "env": {
        "MARIADB_HOST": "localhost",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your_username",
        "MARIADB_PASSWORD": "your_password",
        "MARIADB_DATABASE": "your_database"
      }
    }
  }
}

Security features and behavior

The server can run in read-only mode by default, allowing only SELECT, SHOW, DESCRIBE, and EXPLAIN queries. To enable write operations, set the read-only flag to false in the environment variables.

SQL injection prevention is achieved through parameterized queries, automatic stripping of SQL comments, and validation before execution. Connection pooling and configurable timeouts help maintain performance and reliability.

Usage examples

Explore the database structure by listing databases, then lists tables in a chosen database, and finally inspect a table's schema.

Query data by asking for top results, recent records, or aggregated metrics. You can paginate results using limit and offset to navigate large datasets.

Troubleshooting and tips

Common issues include connection errors, missing MariaDB Connector/C, permission problems, and query timeouts. Verify credentials, ensure the connector is installed, and check user permissions. If queries time out, consider simplifying the query or increasing limits.

list_databases

List all accessible databases on the MariaDB server.

list_tables

List all tables in a specific database with metadata.

get_table_schema

Get detailed schema information for a specific table.

execute_query

Execute SQL queries against the database with optional parameters and pagination.

get_database_stats

Get statistics and metadata about a database.