# Clone the repository
git clone https://github.com/your-org/mysql-mcp-server.git
cd mysql-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your MySQL credentials

DB_HOST=localhost
DB_PORT=3306
DB_NAME=my_database
DB_USER=my_user
DB_PASSWORD=my_secure_password

# Development (with MCP Inspector)
mcp dev app/server.py

# Production (stdio transport)
python -m app.server

# Production (HTTP transport)
TRANSPORT=http HTTP_PORT=8000 python -m app.server

docker compose up -d

docker build -t mysql-mcp-server .
docker run -it --rm \
  -e DB_HOST=your-mysql-host \
  -e DB_PORT=3306 \
  -e DB_NAME=your_database \
  -e DB_USER=your_user \
  -e DB_PASSWORD=your_password \
  mysql-mcp-server

READ_ONLY_MODE=false          # Disable all writes
MAX_RETURNED_ROWS=10000       # Max rows per query
QUERY_TIMEOUT=30              # Seconds before query timeout
ENABLE_QUERY_VALIDATION=true  # Enable all security checks
BLOCKED_KEYWORDS=             # Additional blocked keywords (CSV)

Show me all tables in the database
What columns does the users table have?
Count all active users
Find users with "john" in their name or email
Show the 5 most recent orders
What indexes exist on the orders table?
Show me the foreign keys on the order_items table
Get the CREATE TABLE statement for users
Run: SELECT u.name, COUNT(o.id) as orders FROM users u JOIN orders o ON u.id = o.user_id GROUP BY u.name
What's the database health status?
Show MySQL timeout variables
Explain this query: SELECT * FROM users WHERE email LIKE '%@example.com%'
Bulk insert 100 users from a JSON array
Upsert a user record (insert or update on duplicate)
What are the statistics for the 'amount' column in the orders table?
Show me a summary of the users table
How big is my database? Show table sizes
Compare two queries to find data differences
Export the active users as CSV
Show the query history
What's the connection pool utilization?
Find all tables related to the 'orders' table
Show me the complete relationship map of all tables
Analyze the users table for better query performance
Add a new column 'phone' to the users table
Show all triggers on the orders table
Show all views in the database

mysql-mcp-server/
├── app/
│   ├── server.py          # MCP server entrypoint
│   ├── config.py          # Pydantic Settings configuration
│   ├── database.py        # SQLAlchemy connection management
│   ├── security.py        # Query validation & security
│   ├── logger.py          # Loguru structured logging
│   ├── tools/             # MCP tool implementations
│   │   ├── database_info.py      # ping, version, health, list_databases
│   │   ├── list_tables.py        # list_tables
│   │   ├── describe_table.py     # describe, indexes, foreign_keys, columns
│   │   ├── get_schema.py         # CREATE TABLE DDL
│   │   ├── execute_select.py     # SELECT, search, count, paginate
│   │   ├── insert_record.py      # INSERT operations
│   │   ├── update_record.py      # UPDATE operations
│   │   ├── delete_record.py      # DELETE operations
│   │   ├── bulk_operations.py    # bulk_insert, upsert, create_table_from_select
│   │   ├── table_management.py   # analyze, optimize, rename, add/drop/modify column, triggers, views, procedures
│   │   ├── analytics.py          # column_statistics, table_data_summary, database_size, data_diff
│   │   ├── export_tools.py       # export_results, query_history, connection_stats, relationship tools
│   │   ├── execute_sql.py        # Arbitrary SQL execution
│   │   ├── transaction.py        # Transaction management
│   │   └── utility_tools.py      # SHOW STATUS, VARIABLES, etc.
│   ├── models/
│   │   └── schemas.py    # Pydantic v2 input/output models
│   └── utils/
├── tests/
│   ├── conftest.py       # Fixtures and test configuration
│   ├── test_security.py  # Security validation tests
│   ├── test_config.py    # Configuration tests
│   ├── test_database.py  # Database manager tests
│   └── test_tools.py     # MCP tool integration tests
├── docker/
│   └── init.sql          # Sample database initialization
├── .env.example          # Environment variable template
├── Dockerfile            # Multi-stage production build
├── docker-compose.yml    # Full stack with MySQL
├── requirements.txt      # Runtime dependencies
├── requirements-dev.txt  # Development dependencies
├── pyproject.toml        # Project config, tools, linting
└── README.md

# All tests
pytest

# With coverage
pytest --cov=app --cov-report=html

# Unit tests only (no integration)
pytest -m "not integration"

# Specific test file
pytest tests/test_security.py -v

# Linting
ruff check app/ tests/

# Auto-fix
ruff check --fix app/ tests/

# Formatting
black app/ tests/

# Type checking
mypy app/

# Verify MySQL is running
mysql -h localhost -u root -p

# Check Docker status
docker compose ps

# View MCP server logs
docker compose logs mcp

# Verify credentials in .env
cat .env

# Test connection manually
mysql -h $DB_HOST -P $DB_PORT -u $DB_USER -p$DB_PASSWORD $DB_NAME

QUERY_TIMEOUT=60

READ_ONLY_MODE=false