Db Navigator
    Db Navigator

    Db Navigator

    A powerful MySQL/MariaDB database navigation MCP (Model Control Protocol) to be installed in Cursor, Claude or other tools that accept mcps for easy database querying and management.

    3.3

    GitHub Stats

    Stars

    4

    Forks

    1

    Release Date

    5/7/2025

    about 2 months ago

    Detailed Description

    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 .
    
    1. 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

    1. fork the repository
    2. create your feature branch (git checkout -b feature/amazing-feature)
    3. commit your changes (git commit -m 'add some amazing feature')
    4. push to the branch (git push origin feature/amazing-feature)
    5. open a pull request

    license

    this project is licensed under the mit license - see the license file for details.

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.