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

Python 3.8+ installed on your system
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

Connection Error: Verify your database credentials and that MariaDB is running
MariaDB Connector/C Not Found: Ensure you've installed the connector and set MARIADB_CONFIG
Permission Denied: Check that your database user has appropriate permissions
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

Use Indexes: Ensure your tables have appropriate indexes for common queries
Limit Results: Always use LIMIT clauses for large tables
Parameterized Queries: Use parameters instead of string concatenation
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:

Check the troubleshooting section
Review environment variable configuration
Ensure MariaDB Connector/C is properly installed
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.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.gitignore		.gitignore
.mcp.example.json		.mcp.example.json
CLAUDE_CODE_SETUP.md		CLAUDE_CODE_SETUP.md
QUICK_START.md		QUICK_START.md
README.md		README.md
config.example.json		config.example.json
config_examples.md		config_examples.md
mariadb_mcp_server.py		mariadb_mcp_server.py
requirements.txt		requirements.txt
setup.sh		setup.sh
test_connection.py		test_connection.py

Uh oh!

Uh oh!

akworob/mariadb_mcp_server

Folders and files

Latest commit

History

Repository files navigation

MariaDB MCP Server

Features

Installation

Prerequisites

Installing MariaDB Connector/C

Install Dependencies

Configuration

Environment Variables

Claude Desktop Configuration

Alternative: Using uvx (Recommended for easy updates)

Available Tools

1. list_databases

2. list_tables

3. get_table_schema

4. execute_query

5. get_database_stats

Security Features

Read-Only Mode

SQL Injection Prevention

Connection Security

Usage Examples

Example 1: Explore Database Structure

Example 2: Query Data

Example 3: Data Analysis

Troubleshooting

Common Issues

Debug Mode

Performance Optimization

Best Practices

Response Size Management

Development

Testing the Server

Extending the Server

License

Support

Changelog

Version 1.0.0 (Current)

Roadmap

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages