MySQL Database Server

# MCP Configuration Examples This document provides ready-to-use `.mcp.json` configuration examples for different scenarios. ## Table of Contents - [Configuration for Claude Code](#configuration-for-claude-code) - [Configuration for Codex CLI](#configuration-for-codex-cli) - [Read-Only Mode (Recommended)](#read-only-mode-recommended) - [Development Mode](#development-mode) - [Multiple Databases](#multiple-databases) - [Remote Database](#remote-database) - [Docker Database](#docker-database) - [Full Configuration Reference](#full-configuration-reference) --- ## Configuration for Claude Code **File Location**: - Linux: `~/.config/claude-code/.mcp.json` - macOS: `~/Library/Application Support/Claude Code/.mcp.json` - Windows: `%APPDATA%\Claude Code\.mcp.json` ### Minimal Setup ```json { "mcpServers": { "mysql": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "your_username", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database" } } } } ``` **Note**: Replace `/absolute/path/to/` with your actual path. Get it with: ```bash cd mcp-mysql-server && pwd # Output: /home/username/mcp-mysql-server (use this path) ``` --- ## Configuration for Codex CLI **File Location**: Codex CLI typically uses one of these locations (check Codex CLI docs for your specific version): - Linux: `~/.config/codex/config.json` - macOS: `~/Library/Application Support/Codex/config.json` - Project-specific: `.codex/config.json` (in your project root) ### Basic Codex CLI Setup ```json { "mcpServers": { "mysql": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "your_username", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` ### Codex CLI - Read-Only for Production Perfect for querying production databases safely: ```json { "mcpServers": { "mysql-prod": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "prod-db.company.com", "MYSQL_PORT": "3306", "MYSQL_USER": "readonly_user", "MYSQL_PASS": "readonly_password", "MYSQL_DB": "production", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **Usage in Codex CLI**: ```bash codex > Query the production database for users created last week ``` ### Codex CLI - Local Development For local development with write access: ```json { "mcpServers": { "mysql-local": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "dev_user", "MYSQL_PASS": "dev_password", "MYSQL_DB": "local_dev", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "true", "ALLOW_DELETE_OPERATION": "true" } } } } ``` **Usage**: ```bash codex > Insert a test user into the database > Update the user's email > Delete the test user ``` ### Codex CLI - Multiple Databases Connect to multiple databases for different purposes: ```json { "mcpServers": { "mysql-analytics": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "analytics-db.company.com", "MYSQL_PORT": "3306", "MYSQL_USER": "analyst", "MYSQL_PASS": "analyst_password", "MYSQL_DB": "analytics", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } }, "mysql-reporting": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "reporting-db.company.com", "MYSQL_PORT": "3306", "MYSQL_USER": "reporter", "MYSQL_PASS": "reporter_password", "MYSQL_DB": "reporting", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **Usage**: ```bash codex > From the analytics database, show me daily active users > In the reporting database, create a new report entry ``` ### Codex CLI - Project-Specific Config Create a project-specific config in `.codex/config.json`: ```json { "mcpServers": { "project-db": { "command": "node", "args": ["../mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "project_user", "MYSQL_PASS": "project_password", "MYSQL_DB": "project_db", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "true", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **Note**: Can use relative paths for project-specific configs. ### Codex CLI Testing After setup: ```bash # Start Codex CLI codex # Test commands > Show me the MySQL database information > List all tables > Query the users table > Try to insert a record (should be blocked if disabled) ``` --- ## Read-Only Mode (Recommended) Best for production databases or when you only need to query data. ```json { "mcpServers": { "mysql": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "readonly_user", "MYSQL_PASS": "secure_password", "MYSQL_DB": "production_db", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **MySQL User Setup**: ```sql CREATE USER 'readonly_user'@'localhost' IDENTIFIED BY 'secure_password'; GRANT SELECT ON production_db.* TO 'readonly_user'@'localhost'; FLUSH PRIVILEGES; ``` --- ## Development Mode For development/testing environments where you need write access. ```json { "mcpServers": { "mysql-dev": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "dev_user", "MYSQL_PASS": "dev_password", "MYSQL_DB": "development_db", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "true", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **Note**: DELETE is still disabled for safety. Enable only if needed. --- ## Multiple Databases Connect to multiple databases simultaneously (e.g., production + development). ```json { "mcpServers": { "mysql-production": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "prod-db.example.com", "MYSQL_PORT": "3306", "MYSQL_USER": "prod_readonly", "MYSQL_PASS": "prod_password", "MYSQL_DB": "production", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } }, "mysql-staging": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "staging-db.example.com", "MYSQL_PORT": "3306", "MYSQL_USER": "staging_user", "MYSQL_PASS": "staging_password", "MYSQL_DB": "staging", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "true", "ALLOW_DELETE_OPERATION": "false" } }, "mysql-local": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "local_password", "MYSQL_DB": "local_dev", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "true", "ALLOW_DELETE_OPERATION": "true" } } } } ``` **Usage**: Claude will ask which database to use, or you can specify: - "Query the production database..." - "In staging, show me..." - "Use the local database to..." --- ## Remote Database Connect to a remote MySQL server. ```json { "mcpServers": { "mysql-remote": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "db.example.com", "MYSQL_PORT": "3306", "MYSQL_USER": "remote_user", "MYSQL_PASS": "secure_password", "MYSQL_DB": "remote_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **Security Tips**: - Use SSH tunnel for added security: ```bash ssh -L 3307:localhost:3306 user@db.example.com ``` Then use `MYSQL_HOST: "localhost"` and `MYSQL_PORT: "3307"` - Use SSL/TLS connections - Whitelist your IP address --- ## Docker Database Connect to MySQL running in Docker. ```json { "mcpServers": { "mysql-docker": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "docker_password", "MYSQL_DB": "myapp", "ALLOW_INSERT_OPERATION": "true", "ALLOW_UPDATE_OPERATION": "true", "ALLOW_DELETE_OPERATION": "true" } } } } ``` **Docker Compose Example**: ```yaml services: mysql: image: mysql:8.0 ports: - "3306:3306" environment: MYSQL_ROOT_PASSWORD: docker_password MYSQL_DATABASE: myapp ``` **Using Docker Network**: If MCP server runs in Docker too, use container name: ```json "MYSQL_HOST": "mysql-container-name" ``` --- ## Using Bun Instead of Node If you have Bun installed (faster): ```json { "mcpServers": { "mysql": { "command": "bun", "args": ["run", "/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "your_username", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database" } } } } ``` --- ## Full Configuration Reference Complete example with all possible options: ```json { "mcpServers": { "mysql": { "command": "node", "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"], "env": { // Required: Database Connection "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "username", "MYSQL_PASS": "password", "MYSQL_DB": "database_name", // Optional: Operation Permissions (default: false) "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" // Note: DROP, TRUNCATE, ALTER are always blocked } } } } ``` --- ## Platform-Specific Locations ### Claude Code **Linux**: ```bash ~/.config/claude-code/.mcp.json ``` **macOS**: ```bash ~/Library/Application Support/Claude Code/.mcp.json ``` **Windows**: ``` %APPDATA%\Claude Code\.mcp.json ``` Or in PowerShell: ```powershell $env:APPDATA\Claude Code\.mcp.json ``` ### Codex CLI **Linux**: ```bash ~/.config/codex/config.json # or ~/.codex/config.json ``` **macOS**: ```bash ~/Library/Application Support/Codex/config.json # or ~/.codex/config.json ``` **Windows**: ``` %APPDATA%\Codex\config.json ``` **Project-Specific** (any platform): ```bash .codex/config.json # in your project root ``` --- ## Getting Your Absolute Path ### Linux/macOS ```bash cd /path/to/mcp-mysql-server pwd # Output: /home/username/projects/mcp-mysql-server ``` Use the output in your `.mcp.json`: ```json "args": ["/home/username/projects/mcp-mysql-server/dist/index.js"] ``` ### Windows ```cmd cd C:\path\to\mcp-mysql-server cd # Output: C:\Users\username\projects\mcp-mysql-server ``` Use forward slashes in JSON: ```json "args": ["C:/Users/username/projects/mcp-mysql-server/dist/index.js"] ``` --- ## Testing Your Configuration After creating `.mcp.json`: 1. **Restart Claude Code** 2. **Verify Connection**: ``` Show me the MySQL database information ``` 3. **List Tables**: ``` What tables are in my database? ``` 4. **Test Safety**: ``` Try to insert a test record ``` Should be blocked if `ALLOW_INSERT_OPERATION: "false"` --- ## Troubleshooting ### Server Not Found - Check path is **absolute** (not relative) - Verify `dist/index.js` exists: `ls /path/to/mcp-mysql-server/dist/index.js` - Restart Claude Code after config changes ### Connection Errors - Test MySQL connection: `mysql -h HOST -u USER -p DATABASE` - Check host, port, username, password - Verify MySQL is running - Check firewall settings ### Permission Issues - Verify MySQL user has required grants - Check `ALLOW_*_OPERATION` values are "true" or "false" (strings) - Ensure MySQL user has SELECT permission at minimum ### JSON Syntax Errors - Validate JSON: https://jsonlint.com/ - Check for trailing commas (not allowed in JSON) - Ensure proper quotes (double quotes only) - Verify all braces are balanced --- ## Security Best Practices 1. **Never Commit .mcp.json with Passwords** ```bash # Add to .gitignore .mcp.json ``` 2. **Use Environment-Specific Users** - Production: Read-only user - Development: Limited write access - Local: Full access OK 3. **Strong Passwords** ```bash # Generate strong password openssl rand -base64 32 ``` 4. **Least Privilege** ```sql -- Only grant what's needed GRANT SELECT, INSERT ON mydb.* TO 'user'@'localhost'; ``` 5. **Network Security** - Use localhost when possible - Use SSH tunnels for remote connections - Enable MySQL SSL/TLS - Firewall MySQL port --- ## Example: Complete Setup **1. Create .mcp.json**: ```bash mkdir -p ~/.config/claude-code nano ~/.config/claude-code/.mcp.json ``` **2. Paste Configuration**: ```json { "mcpServers": { "mysql": { "command": "node", "args": ["/home/yourusername/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "localhost", "MYSQL_PORT": "3306", "MYSQL_USER": "myapp_user", "MYSQL_PASS": "secure_password_here", "MYSQL_DB": "myapp_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` **3. Create MySQL User**: ```sql CREATE USER 'myapp_user'@'localhost' IDENTIFIED BY 'secure_password_here'; GRANT SELECT ON myapp_database.* TO 'myapp_user'@'localhost'; FLUSH PRIVILEGES; ``` **4. Test**: ```bash mysql -u myapp_user -p myapp_database -e "SELECT 1" ``` **5. Restart Claude Code** **6. Verify in Claude**: ``` Show me the MySQL database information ``` --- ## Quick Copy-Paste Template Replace the placeholders and you're ready to go! ```json { "mcpServers": { "mysql": { "command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/mcp-mysql-server/dist/index.js"], "env": { "MYSQL_HOST": "REPLACE_WITH_HOST", "MYSQL_PORT": "REPLACE_WITH_PORT", "MYSQL_USER": "REPLACE_WITH_USERNAME", "MYSQL_PASS": "REPLACE_WITH_PASSWORD", "MYSQL_DB": "REPLACE_WITH_DATABASE", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false" } } } } ``` --- **Need more help?** See the [main README](../README.md) or [Quick Start Guide](QUICKSTART.md)