mcp-db-navigator

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.