https://github.com/medsaad/mcp-db-navigator
A powerful MySQL/MariaDB database navigation tool using MCP (Model Control Protocol) for easy database querying and management.
https://github.com/medsaad/mcp-db-navigator
Last synced: 5 months ago
JSON representation
A powerful MySQL/MariaDB database navigation tool using MCP (Model Control Protocol) for easy database querying and management.
- Host: GitHub
- URL: https://github.com/medsaad/mcp-db-navigator
- Owner: Medsaad
- License: mit
- Created: 2025-05-04T13:30:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-05-04T15:22:56.000Z (5 months ago)
- Last Synced: 2025-05-04T15:36:42.855Z (5 months ago)
- Language: Python
- Size: 16.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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\\.mcp\mcp-db.log`
- **macOS/Linux:** `/home//.mcp/mcp-db.log` or `/Users//.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
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.