Ejota93/mysql_mcp_server

MySQL MCP Server

A Model Context Protocol (MCP) implementation that enables secure interaction with MySQL databases. This server component facilitates communication between AI applications (hosts/clients) and MySQL databases, making database exploration and analysis safer and more structured through a controlled interface.

Note: MySQL MCP Server is not designed to be used as a standalone server, but rather as a communication protocol implementation between AI applications and MySQL databases.

🚀 Available Implementations

This repository now provides two complete implementations:

📄 JavaScript Implementation (Recommended)

• Language: Modern JavaScript (ES6+) with Node.js
• Dependencies: @modelcontextprotocol/sdk, mysql2, dotenv
• Features: All original functionality with improved performance
• Tests: Full Jest test suite

🐍 Python Implementation (Original)

• Language: Python 3.11+
• Dependencies: mcp, mysql-connector-python
• Features: Original implementation with full MCP compatibility
• Tests: PyTest test suite

🎯 Quick Start

JavaScript Version (Recommended)

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your MySQL credentials

# Run the server
npm start

# Run tests
npm test

Python Version

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
export MYSQL_HOST=localhost
export MYSQL_USER=mcp_user
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=your_database

# Run via MCP client (not directly)

✨ Features

• ✅ Secure MySQL connections with proper authentication
• ✅ SQL query execution through controlled interface
• ✅ Database schema exploration (list tables, describe structure)
• ✅ Table data reading with safety limits
• ✅ Comprehensive error handling and logging
• ✅ Environment-based configuration for security
• ✅ Docker support for easy deployment
• ✅ Full test coverage for both implementations

🔧 Installation & Configuration

System Requirements

For JavaScript:

• Node.js 18.0.0+
• MySQL 5.7+ / 8.0+

For Python:

• Python 3.11+
• MySQL 5.7+ / 8.0+

Database Setup

Create a dedicated MySQL user with minimal permissions:

-- Create user
CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'secure_password';

-- Grant minimal required permissions
GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';

-- For advanced operations (optional)
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE TEMPORARY TABLES 
ON your_database.* TO 'mcp_user'@'localhost';

-- Apply permissions
FLUSH PRIVILEGES;

📚 Usage with AI Applications

Claude Desktop Configuration

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["path/to/mysql_mcp_server/src/server.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Docker Usage

# Build and run with Docker
docker build -t mysql-mcp-server .
docker run -i --rm \
  -e MYSQL_HOST=host.docker.internal \
  -e MYSQL_USER=mcp_user \
  -e MYSQL_PASSWORD=your_password \
  -e MYSQL_DATABASE=your_database \
  mysql-mcp-server

🛠️ Development

JavaScript Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests with watch
npm run test:watch

# Generate coverage report
npm run test:coverage

Python Development

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

📂 Project Structure

mysql_mcp_server/
├── src/                    # JavaScript implementation
│   ├── server.js          # Main MCP server
│   ├── mysql-client.js    # MySQL connection wrapper
│   ├── handlers/          # Request handlers
│   └── utils/             # Utilities (config, logging)
├── src/mysql_mcp_server/  # Python implementation  
│   └── server.py          # Python MCP server
├── tests/                 # JavaScript tests
├── tests/                 # Python tests
├── package.json           # Node.js configuration
├── requirements.txt       # Python dependencies
└── README.md             # This file

🔐 Security Considerations

• ✅ Never commit environment variables or credentials
• ✅ Use a database user with minimal required permissions
• ✅ Consider implementing query whitelisting for production use
• ✅ Monitor and log all database operations
• ✅ Regular security reviews of database access

See for detailed security configuration.

🏆 Why Choose JavaScript Implementation?

The JavaScript version offers several advantages:

• Better Performance: Native async/await and connection pooling
• Modern Ecosystem: Extensive npm package ecosystem
• Easier Deployment: Single runtime, simpler Docker images
• Active Development: Regular updates and maintenance
• Better Testing: Comprehensive Jest test suite

📄 License

MIT License - see file for details.

🤝 Contributing

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

📞 Support

• Issues: GitHub Issues
• Documentation: See implementation-specific README files
• Security: Report security issues responsibly via GitHub

Choose your preferred implementation and start building amazing AI-powered database interactions! 🚀