qtyty/mysql-mcp-server

MySQL MCP Server

A Model Context Protocol (MCP) server implementation for MySQL databases using the official mcp-go framework.

Features

• 🚀 Fast & Efficient : Built with Go and the official mcp-go framework
• 🔒 Secure : SQL injection protection, query validation, and access controls
• 🛠️ Complete : Full set of MySQL tools for database operations
• 📊 Rich Output : Both text and JSON formatted responses
• 🔧 Configurable : Flexible configuration for security and performance
• 🌐 Multiple Transports : Supports stdio and HTTP modes

Supported Tools

Installation

Prerequisites

• Go 1.21 or later
• MySQL 5.7+ or MariaDB 10.2+
• Access to a MySQL database

Quick Start

1. Clone the repository

   git clone <repository-url>
   cd mysql-mcp-server
   

2. Install dependencies

   make deps
   

3. Configure the database

   cp configs/config.yaml.example configs/config.yaml
   # Edit configs/config.yaml with your database settings
   

4. Build and run

   make build
   make run
   

Configuration

Create a configs/config.yaml file:

database:
  host: "localhost"
  port: 3306
  username: "your_username"
  password: "your_password"
  database: "your_database"
  max_connections: 10
  idle_connections: 5
  connection_lifetime: 3600s
  connect_timeout: 10s

security:
  allowed_operations:
    - "SELECT"
    - "INSERT"
    - "UPDATE"
    - "DELETE"
    - "DESCRIBE"
    - "SHOW"
  max_query_time: 30s
  max_result_rows: 1000
  enable_whitelist: false
  whitelist_tables: []
  read_only: false

logging:
  level: "info"
  format: "json"
  output: "stdout"
  enable_file: false
  file_path: "logs/mcp-server.log"

Usage

Stdio Mode (Default)

Perfect for use with MCP clients like Claude Desktop:

# Run in stdio mode
make run

# Or explicitly
make run-stdio

HTTP Mode

For web-based integrations:

# Run HTTP server on port 3001
make run-http

# Or with custom port
./bin/mysql-mcp-server -config configs/config.yaml -http -port 8080

Development Mode

Run without building:

# Stdio mode
make run-dev

# HTTP mode  
make run-dev-http

Tool Examples

Query Database

{
  "name": "query_database",
  "arguments": {
    "sql": "SELECT id, name, email FROM users WHERE created_at > ?",
    "params": ["2024-01-01"],
    "limit": 10
  }
}

Execute Statement

{
  "name": "execute_statement",
  "arguments": {
    "sql": "INSERT INTO users (name, email) VALUES (?, ?)",
    "params": ["John Doe", "john@example.com"]
  }
}

Describe Table

{
  "name": "describe_table",
  "arguments": {
    "table_name": "users"
  }
}

List Tables

{
  "name": "list_tables",
  "arguments": {}
}

Integration with Claude Desktop

1. Install Claude Desktop from Anthropic
2. Configure MCP server in Claude Desktop settings:

   {
     "mcpServers": {
       "mysql": {
         "command": "/path/to/mysql-mcp-server/bin/mysql-mcp-server",
         "args": ["-config", "/path/to/config.yaml", "-stdio"]
       }
     }
   }
   

3. Restart Claude Desktop and start using MySQL tools in your conversations

Security Features

• SQL Injection Protection : Query validation and parameterized queries
• Operation Whitelist : Control which SQL operations are allowed
• Table Whitelist : Restrict access to specific tables
• Query Limits : Timeout and row count limits
• Read-Only Mode : Disable all write operations

Development

Project Structure

mysql-mcp-server/
├── cmd/server/          # Main application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database connection and operations
│   └── tools/           # MCP tool implementations
├── configs/             # Configuration files
├── bin/                 # Built binaries
└── Makefile            # Build and development commands

Available Make Commands

make help           # Show all available commands
make deps           # Download dependencies
make build          # Build the application
make run            # Run in stdio mode
make run-http       # Run in HTTP mode
make test           # Run tests
make test-cover     # Run tests with coverage
make format         # Format Go code
make lint           # Run linter
make clean          # Clean build artifacts

Testing

# Run all tests
make test

# Run tests with coverage
make test-cover

# Test with a real database (ensure MySQL is running)
make test-tools

Troubleshooting

Common Issues

1. Database Connection Failed
   • Check MySQL server is running
   • Verify credentials in config.yaml
   • Ensure database exists and user has proper permissions
2. Permission Denied
   • Check MySQL user permissions
   • Verify allowed_operations in security config
   • Check table whitelist if enabled
3. Query Timeout
   • Increase max_query_time in config
   • Optimize your SQL queries
   • Check database performance

Logging

Enable file logging for debugging:

logging:
  level: "debug"
  enable_file: true
  file_path: "logs/mcp-server.log"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run make lint and make test
6. Submit a pull request

License

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

Acknowledgments

• Built with mcp-go - The official Go framework for MCP
• Uses go-sql-driver/mysql for MySQL connectivity
• Inspired by the Model Context Protocol specification