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 .

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