wsmxd/mcp-mysql-server

MCP MySQL Server

A Model Context Protocol (MCP) server for MySQL database operations, supporting both Streamable HTTP and STDIO transport.

Features

• MCP Protocol Support: Full implementation of Model Context Protocol
• Streamable HTTP: Server-Sent Events (SSE) based streaming for web compatibility
• STDIO Mode: Traditional stdin/stdout for process-based communication
• MySQL Operations: Execute queries, manage tables, and inspect database schema

Available Tools

1. query - Execute SELECT queries and return formatted results
2. execute - Execute INSERT, UPDATE, DELETE, and other modification queries
3. list_tables - List all tables in the connected database
4. describe_table - Get detailed schema information for a specific table

Installation

Prerequisites

• Go 1.21 or later
• MySQL database

Build from source

# Clone the repository (if applicable)
cd mcp-mysql-server

# Download dependencies
go mod download

# Build the binary
go build -o mcp-mysql-server

Usage

HTTP Mode (Streamable)

# Start the server on default port 8080
./mcp-mysql-server -mode http -dsn "user:password@tcp(localhost:3306)/database"

# Custom port
./mcp-mysql-server -mode http -port 3000 -dsn "user:password@tcp(localhost:3306)/database"

The server will be available at:

• MCP Endpoint: http://localhost:8080/mcp
• Health Check: http://localhost:8080/health

STDIO Mode

./mcp-mysql-server -mode stdio -dsn "user:password@tcp(localhost:3306)/database"

Using Environment Variable

export MYSQL_DSN="user:password@tcp(localhost:3306)/database"
./mcp-mysql-server -mode http

Configuration

MySQL DSN Format

user:password@tcp(host:port)/database?param=value

Examples:

root:mypassword@tcp(localhost:3306)/mydb
admin:secret@tcp(192.168.1.100:3306)/production?charset=utf8mb4
user:pass@tcp(mysql.example.com:3306)/testdb?parseTime=true

MCP Protocol Examples

Initialize Connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Execute a Query

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "sql": "SELECT * FROM users LIMIT 10"
    }
  }
}

Execute a Modification

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "execute",
    "arguments": {
      "sql": "INSERT INTO users (name, email) VALUES ('John', 'john@example.com')"
    }
  }
}

List Tables

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_tables",
    "arguments": {}
  }
}

Describe Table

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "describe_table",
    "arguments": {
      "table": "users"
    }
  }
}

Testing with curl

# Health check
curl http://localhost:8080/health

# List tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Execute query
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query",
      "arguments": {
        "sql": "SELECT * FROM users LIMIT 5"
      }
    }
  }'

Security Considerations

⚠️ Important: This server executes SQL queries directly. Use appropriate security measures:

• Never expose the server directly to the internet
• Use strong database credentials
• Consider running in a restricted network environment
• Implement authentication/authorization if needed
• Use read-only database users when possible
• Validate and sanitize inputs in production

Development

Project Structure

.
├── main.go          # Application entry point
├── mcp_types.go     # MCP protocol type definitions
├── mcp_server.go    # MCP server logic and tool handlers
├── db.go            # MySQL database operations
├── server.go        # HTTP and STDIO server implementations
└── go.mod           # Go module dependencies

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.