# MCP MySQL Server - Setup Checklist
Use this checklist to get your server up and running!
## ✅ Initial Setup
- [ ] Run `./setup.sh` for automated setup
- OR manually: `bun install` / `npm install`
- OR manually: `cp .env.example .env`
- OR manually: `bun run build` / `npm run build`
- [ ] Configure `.env` file with your MySQL credentials
```bash
nano .env
# Update: MYSQL_HOST, MYSQL_USER, MYSQL_PASS, MYSQL_DB
```
- [ ] Test database connection
```bash
mysql -h localhost -u your_user -p your_database -e "SELECT 1"
```
- [ ] Verify build succeeded
```bash
ls -la dist/index.js
# Should show ~12 KB file
```
## ✅ Claude Code Integration
- [ ] Locate Claude Code config directory
- Linux: `~/.config/claude-code/`
- macOS: `~/Library/Application Support/Claude Code/`
- Windows: `%APPDATA%\Claude Code\`
- [ ] Edit or create `.mcp.json`
```bash
nano ~/.config/claude-code/.mcp.json
```
- [ ] Add MySQL server configuration (update path!)
```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"
}
}
}
}
```
- [ ] Restart Claude Code
- [ ] Verify connection in Claude Code
- Ask: "Show me the MySQL database information"
- Should see connection details and permissions
## ✅ Codex CLI Integration
- [ ] Locate Codex CLI config file
- Check Codex CLI documentation for exact path
- [ ] Add same configuration as Claude Code above
- [ ] Test Codex CLI
```bash
codex
> Show me the MySQL database information
```
## ✅ First Tests
- [ ] List tables
```
What tables are in my database?
```
- [ ] Describe a table
```
Show me the structure of the [table_name] table
```
- [ ] Query data
```
Show me the first 10 rows from [table_name]
```
- [ ] Test safety features
```
Try to insert a test record
```
Should be blocked with error message
## ✅ Optional: GitHub Setup
- [ ] Update repository URL in [package.json](package.json:35)
```json
"repository": {
"type": "git",
"url": "https://github.com/YOUR_USERNAME/mcp-mysql-server.git"
}
```
- [ ] Update homepage in [package.json](package.json:40)
```json
"homepage": "https://github.com/YOUR_USERNAME/mcp-mysql-server#readme"
```
- [ ] Update funding links in [.github/FUNDING.yml](.github/FUNDING.yml)
- Add your GitHub Sponsors, Ko-fi, Patreon, etc.
- [ ] Initialize git repository (if not already)
```bash
git init
git add .
git commit -m "Initial commit with improvements"
```
- [ ] Push to GitHub
```bash
git remote add origin https://github.com/YOUR_USERNAME/mcp-mysql-server.git
git branch -M main
git push -u origin main
```
- [ ] Enable GitHub Actions
- Go to repository Settings → Actions → Enable
## ✅ Security Checklist
- [ ] `.env` file is in `.gitignore` ✅ (already done)
- [ ] Strong MySQL password configured
- [ ] Using read-only mode by default ✅ (already configured)
- [ ] MySQL user has minimal required permissions
- [ ] Network access to MySQL is restricted
- [ ] Review [.github/SECURITY.md](.github/SECURITY.md) for best practices
## ✅ Documentation Review
- [ ] Read [README.md](README.md) - Main documentation
- [ ] Read [QUICKSTART.md](QUICKSTART.md) - Quick start guide
- [ ] Browse [examples/](examples/) directory
- [ ] [claude-code-setup.md](examples/claude-code-setup.md)
- [ ] [codex-cli-setup.md](examples/codex-cli-setup.md)
- [ ] [usage-examples.md](examples/usage-examples.md)
- [ ] Review [CONTRIBUTING.md](CONTRIBUTING.md) if planning to contribute
## 🎯 Success Criteria
Your setup is complete when:
✅ Build succeeds (`dist/index.js` exists)
✅ Database connection works
✅ MCP client shows server connected
✅ Can query database successfully
✅ Safety features block write operations
✅ Error messages are clear and helpful
## 🚨 Troubleshooting
### Server not found in MCP client
1. Check path in `.mcp.json` is absolute
2. Verify `dist/index.js` exists
3. Restart MCP client
4. Check MCP client logs
### Connection errors
1. Test MySQL connection: `mysql -h HOST -u USER -p DB`
2. Verify credentials in `.env`
3. Check MySQL is running
4. Check firewall settings
### Build errors
1. Run `npm run clean && npm run build`
2. Check Node.js version: `node -v` (need 18+)
3. Reinstall dependencies: `rm -rf node_modules && npm install`
### Permission errors
1. Check MySQL user has required permissions
2. Verify `ALLOW_*_OPERATION` environment variables
3. Check MySQL grants: `SHOW GRANTS FOR 'user'@'host'`
## 📚 Next Steps
After completing setup:
1. **Learn by example**: Open [examples/usage-examples.md](examples/usage-examples.md)
2. **Try queries**: Start with simple SELECT queries
3. **Explore schema**: List tables and describe structures
4. **Analyze data**: Try aggregations and grouping
5. **Enable writes** (if needed): Update `.env` and restart
## 🎉 You're Done!
Congratulations! Your MCP MySQL Server is ready to use.
**Need help?**
- Check [examples/](examples/) for guides
- Read [CONTRIBUTING.md](CONTRIBUTING.md) for development
- Review [.github/SECURITY.md](.github/SECURITY.md) for security
- See [PROJECT_IMPROVEMENTS.md](PROJECT_IMPROVEMENTS.md) for what was added
**Happy querying!** 🚀