MariaDB MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your MariaDB databases. This server provides comprehensive database access with schema exploration, query execution, and advanced features.

Features

• 🔍 Schema Exploration: Browse databases, tables, and detailed schema information
• 📊 Query Execution: Execute both read-only and write queries (configurable)
• 📄 Multiple Output Formats: JSON for programmatic use, Markdown for human readability
• 📑 Pagination Support: Handle large result sets efficiently
• 🔒 Security Features: Parameterized queries, SQL injection prevention, read-only mode
• 🏊 Connection Pooling: Efficient database connection management
• ⚡ Performance: Query timeouts, result size limits, and optimized response formatting

Installation

Prerequisites

1. Python 3.8+ installed on your system
2. MariaDB Connector/C (required for the Python MariaDB connector)

Installing MariaDB Connector/C

On macOS:

brew install mariadb-connector-c
export MARIADB_CONFIG=$(brew --prefix mariadb-connector-c)/bin/mariadb_config

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libmariadb-dev

On RHEL/CentOS/Fedora:

sudo yum install mariadb-connector-c-devel

On Windows: Download and install from MariaDB Connector/C downloads

Install Dependencies

pip install -r requirements.txt

Or install packages individually:

pip install mcp mariadb

Configuration

Environment Variables

Configure the server using these environment variables:

# Required - Database Connection
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)

# Optional - Security & Performance
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

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "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 (Recommended for easy updates)

If you package and publish the server to PyPI:

{
  "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"
      }
    }
  }
}

Available Tools

The server provides the following tools:

1. list_databases

List all accessible databases on the MariaDB server.

Example usage in Claude:

• "What databases are available?"
• "Show me all databases"

2. list_tables

List all tables in a specific database with metadata.

Parameters:

• database_name: Name of the database
• response_format: "json" or "markdown" (default: "markdown")

Example usage in Claude:

• "What tables are in the sales database?"
• "List all tables in my_app database"

3. get_table_schema

Get detailed schema information for a specific table.

Parameters:

• database_name: Name of the database
• table_name: Name of the table
• include_indexes: Include index information (default: true)
• include_foreign_keys: Include foreign key relationships (default: true)
• response_format: "json" or "markdown"

Example usage in Claude:

• "Show me the schema for the users table"
• "What columns does the orders table have?"

4. execute_query

Execute SQL queries against the database.

Parameters:

• database_name: Database to query
• query: SQL query to execute
• parameters: Query parameters for parameterized queries (optional)
• limit: Maximum rows to return (default: 100, max: 1000)
• offset: Number of rows to skip for pagination (default: 0)
• response_format: "json" or "markdown"

Example usage in Claude:

• "Find all users who registered in the last month"
• "Show me the top 10 selling products"
• "Update the status of order 12345 to 'shipped'"

5. get_database_stats

Get statistics and metadata about a database.

Parameters:

• database_name: Name of the database
• response_format: "json" or "markdown"

Example usage in Claude:

• "How large is the analytics database?"
• "Show me statistics for the production database"

Security Features

Read-Only Mode

By default, the server runs in read-only mode, allowing only SELECT, SHOW, DESCRIBE, and EXPLAIN queries. To enable write operations:

export MARIADB_READ_ONLY="false"

SQL Injection Prevention

• The server uses parameterized queries
• SQL comments are automatically stripped
• Query validation is performed before execution

Connection Security

• Connection pooling with automatic reconnection
• Configurable timeouts
• Secure credential handling through environment variables

Usage Examples

Once configured, you can interact with your MariaDB database through Claude:

Example 1: Explore Database Structure

You: "What databases do I have access to?"
Claude: [Uses list_databases tool]

You: "Show me the tables in the ecommerce database"
Claude: [Uses list_tables tool]

You: "What's the structure of the customers table?"
Claude: [Uses get_table_schema tool]

Example 2: Query Data

You: "Find the top 5 customers by total purchase amount"
Claude: [Uses execute_query to run an aggregation query]

You: "Show me all orders from last month"
Claude: [Uses execute_query with date filtering]

Example 3: Data Analysis

You: "Analyze the sales trends for Q4"
Claude: [Uses multiple tools to explore schema and run analytical queries]

You: "What's the average order value by product category?"
Claude: [Uses execute_query with GROUP BY and aggregation]

Troubleshooting

Common Issues

1. Connection Error: Verify your database credentials and that MariaDB is running
2. MariaDB Connector/C Not Found: Ensure you've installed the connector and set MARIADB_CONFIG
3. Permission Denied: Check that your database user has appropriate permissions
4. Query Timeout: Complex queries may timeout; consider optimizing or increasing timeout

Debug Mode

To enable detailed logging:

# In the server file, change:
logging.basicConfig(level=logging.DEBUG)

Performance Optimization

Best Practices

1. Use Indexes: Ensure your tables have appropriate indexes for common queries
2. Limit Results: Always use LIMIT clauses for large tables
3. Parameterized Queries: Use parameters instead of string concatenation
4. Connection Pooling: Adjust MARIADB_POOL_SIZE based on your workload

Response Size Management

• Results are automatically truncated if they exceed 25,000 characters
• Use pagination (limit/offset) for large result sets
• Choose JSON format for programmatic processing, Markdown for readability

Development

Testing the Server

# Test connection
python mariadb_mcp_server.py

# The server will wait for MCP commands on stdin
# Press Ctrl+C to exit

Extending the Server

To add new tools, follow this pattern:

@mcp.tool(
    name="your_tool_name",
    annotations={
        "title": "Human Readable Title",
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
async def your_tool_function(params: YourInputModel) -> str:
    """Tool documentation"""
    # Implementation
    pass

License

MIT License - See LICENSE file for details

Support

For issues, questions, or contributions:

1. Check the troubleshooting section
2. Review environment variable configuration
3. Ensure MariaDB Connector/C is properly installed
4. Verify database permissions

Changelog

Version 1.0.0 (Current)

• Initial release with core functionality
• Schema exploration tools
• Query execution with pagination
• Multiple output formats
• Security features and connection pooling

Roadmap

• [ ] Transaction support for complex operations
• [ ] Query history and caching
• [ ] Advanced query builder assistance
• [ ] Performance profiling tools
• [ ] Backup and restore utilities
• [ ] Vector search capabilities (MariaDB 11.7+)

Credits

Built with the MCP Python SDK (FastMCP) and MariaDB Connector/Python.