scopweb/mcp-go-mysql

Advanced MySQL MCP Server with Intelligent Security

Production-ready MySQL Model Context Protocol (MCP) server in Go with comprehensive database tools, intelligent security system, and SQL injection protection. Features automatic protection for dangerous operations with confirmation keys and modular architecture.

Table of Contents

• Security Notice
• Features
• Installation
• Claude Desktop Configuration
• Usage Examples
• Security Tests
• Project Structure
• Security Configuration
• Documentation

Important Security Notice

ALWAYS BACKUP YOUR DATABASE BEFORE USING WRITE OPERATIONS

This server provides powerful database tools that can modify your data. Please:

• Create backups before performing any write operations
• Test operations on development databases first
• Use appropriate MySQL user permissions - create a dedicated MySQL user with only the permissions you need
• Review SQL statements carefully before execution
• Monitor operation logs for security auditing

Recommended MySQL User Setup

Create a dedicated MySQL user with minimal required permissions:

-- Create dedicated user for MCP
CREATE USER 'mcp_user'@'%' IDENTIFIED BY 'secure_password';

-- Grant only necessary permissions (adjust as needed)
GRANT SELECT, INSERT, UPDATE, DELETE ON your_database.* TO 'mcp_user'@'%';
GRANT CREATE, DROP, ALTER ON your_database.* TO 'mcp_user'@'%';  -- Only if DDL needed
GRANT SHOW VIEW, CREATE VIEW, DROP VIEW ON your_database.* TO 'mcp_user'@'%';

-- Refresh privileges
FLUSH PRIVILEGES;

Never use root or admin users in production!

Features

Database Tools (10 Available)

Security Features

SQL Injection Protection (23+ patterns blocked)

• Classic injection (' OR '1'='1)
• UNION-based injection
• Comment injection (--, #, /* */)
• Stacked queries (;)
• Time-based blind (SLEEP, BENCHMARK)
• Hex encoding attacks
• MySQL-specific: EXTRACTVALUE, UPDATEXML, LOAD_FILE

Dangerous Operation Blocking

Intelligent Risk Assessment

• Small operations (≤100 rows) → Execute freely
• Large operations (>100 rows) → Require confirmation key
• DDL operations (CREATE/DROP/ALTER) → Always require confirmation
• Database drops → Completely blocked

Installation

1. Clone and Build

git clone https://github.com/scopweb/mcp-go-mysql.git
cd mcp-go-mysql
go mod tidy
go build -o mysql-mcp ./cmd

2. Run Security Tests (Recommended)

go test -v ./test/security/...

3. Create Environment File (Optional)

Create .env file in the project directory:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=mcp_user
MYSQL_PASSWORD=secure_password
MYSQL_DATABASE=your_database
LOG_PATH=mysql-mcp.log
ALLOWED_TABLES=users,orders,products  # Optional: whitelist tables
ALLOW_DDL=false                        # Optional: enable DDL operations

Claude Desktop Configuration

Configuration File Location

Windows Configuration

{
  "mcpServers": {
    "mysql": {
      "command": "C:\\Users\\YourUser\\mcp-go-mysql\\mysql-mcp.exe",
      "args": [],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_secure_password",
        "MYSQL_DATABASE": "your_database",
        "LOG_PATH": "C:\\Users\\YourUser\\mcp-go-mysql\\mysql-mcp.log"
      }
    }
  }
}

macOS Configuration

{
  "mcpServers": {
    "mysql": {
      "command": "/Users/youruser/mcp-go-mysql/mysql-mcp",
      "args": [],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_secure_password",
        "MYSQL_DATABASE": "your_database",
        "LOG_PATH": "/Users/youruser/mcp-go-mysql/mysql-mcp.log"
      }
    }
  }
}

Linux Configuration

{
  "mcpServers": {
    "mysql": {
      "command": "/home/youruser/mcp-go-mysql/mysql-mcp",
      "args": [],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_secure_password",
        "MYSQL_DATABASE": "your_database",
        "LOG_PATH": "/home/youruser/mcp-go-mysql/mysql-mcp.log"
      }
    }
  }
}

Docker/Remote MySQL Configuration

{
  "mcpServers": {
    "mysql-remote": {
      "command": "/path/to/mysql-mcp",
      "args": [],
      "env": {
        "MYSQL_HOST": "db.example.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_readonly",
        "MYSQL_PASSWORD": "secure_remote_password",
        "MYSQL_DATABASE": "production_db",
        "ALLOWED_TABLES": "users,orders,products,categories"
      }
    }
  }
}

Environment Variables Reference

Verifying Configuration

After configuring Claude Desktop:

1. Restart Claude Desktop completely
2. Open a new conversation
3. Ask Claude: "What MySQL tools do you have available?"
4. Test connection: "List all tables in my database"

If connection fails, check:

• MySQL server is running and accessible
• Credentials are correct
• Firewall allows connections on the MySQL port
• Log file for error messages

Usage Examples

Safe Operations (No Confirmation Required)

-- Query data
SELECT * FROM products WHERE category='electronics' LIMIT 10

-- Small updates (affects ≤100 rows)
UPDATE orders SET status='shipped' WHERE order_id=12345

-- Describe structures
DESCRIBE customers

-- Count rows
SELECT COUNT(*) FROM users WHERE active=1

Protected Operations (Require Confirmation)

-- Mass updates (requires: confirm_key="PRODUCTION_CONFIRMED_2025")
UPDATE products SET discount=0.1 WHERE category='clearance'

-- DDL operations (always require confirmation)
CREATE VIEW monthly_sales AS
SELECT DATE_FORMAT(date,'%Y-%m') as month, SUM(total)
FROM orders GROUP BY month

Blocked Operations

-- These are ALWAYS blocked for safety:
DROP DATABASE production           -- Database deletion blocked
DELETE FROM users                  -- DELETE without WHERE blocked
UPDATE users SET role='admin'      -- UPDATE without WHERE blocked
SELECT * INTO OUTFILE '/tmp/data'  -- File write blocked
SELECT LOAD_FILE('/etc/passwd')    -- File read blocked

Security Tests

Run the comprehensive security test suite:

# Run all security tests
go test -v ./test/security/...

# Run specific test categories
go test -v ./test/security/... -run "SQL"      # SQL injection tests
go test -v ./test/security/... -run "Path"     # Path traversal tests
go test -v ./test/security/... -run "CVE"      # CVE vulnerability tests

# Run with coverage
go test -v -cover ./test/security/...

# Run benchmarks
go test -bench=. ./test/security/...

Test Coverage

CWE Coverage

Project Structure

mcp-go-mysql/
├── cmd/
│   ├── main.go           # Server entry point
│   ├── types.go          # MCP message structures
│   ├── handlers.go       # Message routing
│   ├── tools.go          # Tool implementations
│   └── security.go       # Security helpers for write operations
├── internal/
│   ├── client.go         # Secure MySQL client with security validation
│   ├── mysql.go          # Database operations and query execution
│   └── analysis.go       # Query analysis and optimization tools
├── test/
│   └── security/
│       ├── security_tests.go    # Dependency & code tests
│       ├── cves_test.go         # CVE & injection tests
│       ├── integration_test.go  # Client integration tests
│       └── README.md            # Test documentation
├── docs/
│   ├── ARCHITECTURE.md          # System architecture
│   ├── CLAUDE_DESKTOP.md        # Claude Desktop setup guide
│   └── SECURITY.md              # Security best practices
├── go.mod
├── go.sum
├── CHANGELOG.md
└── README.md

Security Configuration

Current Settings

• Safety Key: PRODUCTION_CONFIRMED_2025
• Row Limit: 100 rows (operations affecting more require confirmation)

Customizing Security

Edit cmd/main.go:

const (
    SAFETY_KEY    = "YOUR_CUSTOM_KEY_2025"
    MAX_SAFE_ROWS = 50  // Adjust threshold
)

Table Whitelist

Restrict access to specific tables:

# In environment or Claude Desktop config
ALLOWED_TABLES=users,orders,products,categories

Troubleshooting

Connection Issues

# Test MySQL connection
mysql -h localhost -u mcp_user -p your_database

# Check if server is listening
netstat -an | grep 3306

Log Analysis

# View recent logs
tail -f mysql-mcp.log

# Search for errors
grep -i error mysql-mcp.log

Common Errors

Contributing

1. Fork the repository
2. Create a feature branch
3. Run security tests: go test -v ./test/security/...
4. Submit a pull request

Documentation

For detailed documentation, see the docs/ directory:

Quick Links

• New to MCP Go MySQL? Start with
• Understanding the codebase? Read
• Security concerns? Review

License

MIT License - See LICENSE file for details.

Built for production environments with security as the top priority. Always backup your data!

Optimized for Claude Desktop - Seamless integration with Anthropic's Claude Desktop application.