Content
# 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:**
```powershell
mkdir $env:USERPROFILE\.mcp
```
**macOS/Linux:**
```bash
mkdir -p ~/.mcp
```
## Installation
### From PyPI (recommended for most users):
```bash
pip install mcp-db-navigator
```
### From source (for development):
```bash
git clone <your-repo-url>
cd mcp-db
pip install -e .
```
3. Create a `.env` file with your database credentials:
```env
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:
```bash
mcp-db --config /path/to/your/project/.env
```
### 2. In Cursor
To use this MCP server in [Cursor](https://www.cursor.so):
- Open Cursor settings and add a new MCP server.
- Use the following configuration (example):
```json
{
"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.
You Might Also Like
MarkItDown MCP
markitdown-mcp is a lightweight MCP server for converting various URIs to Markdown.
Github
GitHub MCP Server connects AI tools to GitHub for code management and automation.

apisix
Apache APISIX is an API Gateway for managing APIs and microservices.
opik
Opik is a powerful tool for managing and optimizing machine learning experiments.

MCP Toolbox for Databases
MCP Toolbox for Databases is an open-source server simplifying database tool...

sqlglot
SQLGlot is a no-dependency SQL parser and transpiler supporting 30 dialects.