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:

On Ubuntu/Debian:

On RHEL/CentOS/Fedora:

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

Install Dependencies

Or install packages individually:

Configuration

Environment Variables

Configure the server using these environment variables:

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

Alternative: Using uvx (Recommended for easy updates)

If you package and publish the server to PyPI:

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:

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

Example 2: Query Data

Example 3: Data Analysis

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:

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

Extending the Server

To add new tools, follow this pattern:

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.