teamsrunner/mysql-mcp-server repository overview

⁠MySQL MCP Server

A secure and efficient Model Context Protocol (MCP) Server for MySQL database operations. This Docker image provides a standardized interface for database interactions using the MCP protocol, enabling seamless integration with AI assistants and automation tools.

⁠🚀 Quick Start

⁠Using Docker Compose (Recommended)

1. Download the example configuration:

curl -O https://raw.githubusercontent.com/teamsrunner/mysql-mcp-server/main/examples/docker-compose.standalone.yml

1. Start the services:

docker-compose -f docker-compose.standalone.yml up -d

1. Test the connection:

docker exec mysql-mcp-server node -e "console.log('MCP Server is running!')"

⁠Using Docker Run

# Start with existing MySQL
docker run -d \
  --name mysql-mcp-server \
  -e MYSQL_HOST=your-mysql-host \
  -e MYSQL_USER=your-username \
  -e MYSQL_PASSWORD=your-password \
  -e MYSQL_DATABASE=your-database \
  teamsrunner/mysql-mcp-server:latest

⁠📋 Available Tools

The MCP server provides these database operation tools:

⁠🔧 Configuration

⁠Environment Variables

⁠Example .env File

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=myuser
MYSQL_PASSWORD=mypassword
MYSQL_DATABASE=mydatabase

⁠📁 Example Configurations

This repository includes several Docker Compose examples for different use cases:

⁠🏠 Standalone Setup⁠

Complete setup with MySQL database included. Perfect for development and testing.

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: change_this_password
      MYSQL_DATABASE: example_db
  
  mcp-server:
    image: teamsrunner/mysql-mcp-server:latest
    environment:
      MYSQL_HOST: mysql
      MYSQL_PASSWORD: change_this_password
      MYSQL_DATABASE: example_db

⁠🔗 External MySQL⁠

Connect to existing MySQL database server.

⁠🏢 Application Stack⁠

Integration with existing application infrastructure.

⁠🏭 Production Setup⁠

Production-ready configuration with secrets and monitoring.

⁠🔒 Security Features

• SQL Injection Protection: All queries use parameterized statements
• Input Validation: Strict validation of database/table identifiers
• Query Restrictions: Read-only operations for query tool
• Non-Root User: Container runs as unprivileged user (nodejs:1001)
• Error Sanitization: Prevents information leakage in error messages
• Health Monitoring: Built-in health checks and structured logging

⁠🧪 Testing the Setup

⁠Basic Functionality Test

# Test MCP protocol communication
docker exec -i mysql-mcp-server node -e "
const msg = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/list',
  params: {}
};
process.stdin.write(JSON.stringify(msg) + '\\n');
process.stdin.end();
"

⁠Database Operations Test

# Connect to MySQL and verify
docker exec mysql-container mysql -u root -p -e "SHOW DATABASES;"

# Check MCP server logs
docker logs mysql-mcp-server

⁠📚 Documentation

• Docker Hub⁠ - Official image repository
• Examples⁠ - Docker Compose configurations
• Troubleshooting⁠ - Common issues and solutions
• Security Guide⁠ - Security best practices
• API Reference⁠ - MCP protocol tool reference

⁠🤝 Integration Examples

⁠With AI Assistants

The MCP server enables AI assistants to perform database operations:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "database": "sales",
      "query": "SELECT * FROM customers WHERE city = 'New York' LIMIT 10"
    }
  }
}

⁠With Automation Tools

Use in CI/CD pipelines for database setup and testing:

# GitHub Actions example
- name: Setup Test Database
  run: |
    docker run --rm \
      -e MYSQL_HOST=${{ secrets.DB_HOST }} \
      -e MYSQL_USER=${{ secrets.DB_USER }} \
      -e MYSQL_PASSWORD=${{ secrets.DB_PASSWORD }} \
      teamsrunner/mysql-mcp-server:latest

⁠🔍 Troubleshooting

⁠Common Issues

Connection Refused

# Check if MySQL is running
docker ps --filter "name=mysql"

# Verify network connectivity
docker exec mcp-server ping mysql

Authentication Failed

# Verify credentials
docker exec mysql-container mysql -u $MYSQL_USER -p$MYSQL_PASSWORD -e "SELECT 1"

Permission Denied

# Check user permissions
GRANT ALL PRIVILEGES ON database_name.* TO 'username'@'%';
FLUSH PRIVILEGES;

For more troubleshooting information, see docs/TROUBLESHOOTING.md⁠.

⁠🏗️ Development

⁠Building Locally

git clone https://github.com/teamsrunner/mysql-mcp-server.git
cd mysql-mcp-server
docker build -t mysql-mcp-server:local .

⁠Running Tests

# Install dependencies
npm install

# Run comprehensive tests
npm test

# Test with real database
docker-compose -f examples/docker-compose.standalone.yml up -d
node test-comprehensive.js

⁠📄 License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

⁠Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

⁠📞 Support

• Issues: GitHub Issues⁠
• Docker Hub: teamsrunner/mysql-mcp-server⁠
• Discussions: GitHub Discussions⁠

⁠⭐ Show Your Support

If this project helped you, please consider giving it a ⭐ on GitHub!

Note: This is an unofficial implementation of the Model Context Protocol for MySQL. Always follow security best practices when deploying in production environments.