# MCP MySQL Server

A clean, simple, and well-organized Model Context Protocol (MCP) server for MySQL database interactions with Claude Desktop.

## Features

- 🔍 **Query Execution**: Run SQL queries with proper validation and security
- 🗂️ **Multi-Database Support**: Switch between multiple databases easily  
- 🔒 **Security First**: Read-only by default, configurable write permissions
- 📊 **Schema Discovery**: Automatic database and table schema information
- ⚡ **Connection Pooling**: Efficient database connection management
- 🛡️ **Query Validation**: Built-in SQL injection protection
- 📝 **Comprehensive Logging**: Optional detailed logging for debugging

## Quick Start

### 1. Clone and Install
```bash
git clone <your-repo-url>
cd mcp-mysql-server
npm install
```

### 2. Configure Environment
```bash
cp .env.example .env
# Edit .env with your MySQL credentials
```

### 3. Build
```bash
npm run build
```

### 4. Configure Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "mysql-server": {
      "command": "node",
      "args": ["/full/path/to/mcp-mysql-server/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306", 
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "ENABLE_LOGGING": "true"
      }
    }
  }
}
```

## Configuration Options

### Basic Connection
- `MYSQL_HOST`: Database host (default: localhost)
- `MYSQL_PORT`: Database port (default: 3306)  
- `MYSQL_USER`: Database username (default: root)
- `MYSQL_PASSWORD`: Database password
- `MYSQL_DATABASE`: Target database (leave empty for multi-DB mode)
- `MYSQL_SOCKET_PATH`: Unix socket path (optional, overrides host/port)

### Security & Permissions  
- `ALLOW_WRITE`: Enable all write operations (default: false)
- `ALLOW_INSERT`: Enable INSERT statements (default: false)
- `ALLOW_UPDATE`: Enable UPDATE statements (default: false)
- `ALLOW_DELETE`: Enable DELETE statements (default: false)
- `ALLOW_DDL`: Enable DDL operations CREATE/ALTER/DROP (default: false)

### Performance Settings
- `POOL_SIZE`: Connection pool size (default: 10)
- `QUERY_TIMEOUT`: Query timeout in milliseconds (default: 30000)

### Logging
- `ENABLE_LOGGING`: Enable detailed logging (default: false)

## Multi-Database Mode

Leave `MYSQL_DATABASE` empty to enable multi-database mode. This allows querying any database the MySQL user has access to.

Example queries in multi-DB mode:
```sql
-- Use qualified table names
SELECT * FROM database_name.table_name;

-- Switch databases
USE database_name;
SELECT * FROM table_name;
```

## Security Best Practices

1. **Use Read-Only by Default**: Only enable write operations when necessary
2. **Create Dedicated MySQL User**: Don't use root account
3. **Limit Database Access**: Grant permissions only to required databases
4. **Backup Before Writes**: Always backup data before enabling write operations
5. **Monitor Query Logs**: Enable logging to track database activities

## Project Structure

```
src/
├── config/         # Configuration management
├── database/       # Database connection and management  
├── handlers/       # MCP request handlers
├── types/          # TypeScript type definitions
└── utils/          # Utility functions (logger, validator)
```

## Development

```bash
# Development mode with auto-reload
npm run dev

# Watch mode for building
npm run watch

# Run tests
npm test

# Lint code
npm run lint
```