MySQL Navigator MCP

A powerful MySQL/MariaDB database navigation tool using MCP (Model Control Protocol) for easy database querying and management.

Features

Connect to MySQL/MariaDB databases
Switch between different databases dynamically
Execute SQL queries with type safety
Retrieve database schema information
Pydantic model validation for query parameters
Secure credential management
Comprehensive logging system
Connection pooling and retry mechanisms
SSL/TLS support for secure connections

Log File Location (Cross-Platform)

By default, all logs are written to:

Windows: C:\Users\<YourUsername>\.mcp\mcp-db.log
macOS/Linux: /home/<yourusername>/.mcp/mcp-db.log or /Users/<yourusername>/.mcp/mcp-db.log

If the .mcp folder does not exist in your home directory, the application will automatically create it. If you run into any issues, you can manually create the folder:

Windows:

mkdir $env:USERPROFILE\.mcp

macOS/Linux:

mkdir -p ~/.mcp

Installation

From PyPI (recommended for most users):

pip install mcp-db-navigator

From source (for development):

git clone <your-repo-url>
cd mcp-db
pip install -e .

Create a .env file with your database credentials:

DB_HOST=your_host
DB_PORT=your_port
DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password
DB_SSL_CA=/path/to/ssl/ca.pem  # Optional: for SSL/TLS connections
DB_MAX_RETRIES=3  # Optional: number of connection retries
DB_RETRY_DELAY=1.0  # Optional: delay between retries in seconds

Usage Examples

1. Command Line

Run the MCP server directly from your terminal:

mcp-db --config /path/to/your/project/.env

2. In Cursor

To use this MCP server in Cursor:

Open Cursor settings and add a new MCP server.
Use the following configuration (example):

{
  "mcpServers": {
    "mysql-navigator": {
      "command": "mcp-db",
      "args": [
        "--config",
        "/absolute/path/to/your/.env"
      ]
    }
  }
}

Make sure the path to your .env file is absolute.

3. In Claude Desktop

If Claude Desktop supports MCP servers:

Add a new MCP server and point it to the mcp-db command with the --config argument as above.
Refer to Claude Desktop's documentation for details on adding custom MCP servers.

Query Parameters

The query dictionary supports the following parameters:

table_name (required): Name of the table to query
select_fields (optional): List of fields to select (defaults to ["*"])
where_conditions (optional): Dictionary of field-value pairs for WHERE clause
order_by (optional): List of fields to order by
order_direction (optional): Sort direction "ASC" or "DESC" (default: "ASC")
limit (optional): Number of records to return
offset (optional): Number of records to skip
group_by (optional): List of fields to group by
having (optional): Dictionary of field-value pairs for HAVING clause
join_table (optional): Name of the table to join with
join_type (optional): Type of JOIN operation (default: "INNER")
join_conditions (optional): Dictionary of join conditions

Security Features

Database credentials are managed through a config file
Passwords are stored as SecretStr in Pydantic models
Input validation for all query parameters
SQL injection prevention through parameterized queries
SSL/TLS support for encrypted connections
Connection string sanitization
Rate limiting for queries
Query parameter sanitization

Production Features

Error Handling

Comprehensive error handling for database operations
Connection timeout handling
Automatic retry mechanism for failed connections
Input validation for all parameters

Performance

Connection pooling for optimal resource usage
Query execution time logging
Connection pool statistics
Performance metrics collection

Monitoring

Structured logging with different log levels
Query execution tracking
Connection state monitoring
Error rate tracking

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.