Content
# MySQL MCP Tool
A fully functional MySQL MCP (Model Context Protocol) tool that supports interaction with AI assistants through stdio and HTTP/SSE transport methods, enabling query and management of MySQL databases.
## ✨ Features
- **Dual-mode transport**: Supports stdio (standard input/output) and HTTP/SSE transport methods
- **Complete database operations**:
- Query data (SELECT)
- Insert data (INSERT)
- Update data (UPDATE)
- Delete data (DELETE)
- Execute arbitrary SQL
- List all databases
- List all tables
- View table structure (DESCRIBE)
- Create/drop tables (DDL)
- **Dynamic database switching**: Supports switching databases at runtime
- **Access control**: Default read-only mode, configurable to enable write operations
- **Connection pool management**: Uses MySQL connection pool, supports high concurrency
## 📦 Installation
### Method 1: npm Installation (Recommended)
```bash
npm install -g @itkmoon/mysql-mcp
```
Client configuration
```json
{
"mcp": {
"servers": {
"MySQL MCP Tool": {
"command": "npx",
"args": ["-y", "@itkmoon/mysql-mcp"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
}
```
### Method 2: GitHub Clone
```bash
git clone https://github.com/ITKMUnigle/MySQL-MCP-Tool.git
cd MySQL-MCP-Tool
npm install
npm run build
```
## ⚙️ Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|----------|
| `MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |
| `MCP_HTTP_PORT` | HTTP port (only for http mode) | `3000` |
| `MYSQL_HOST` | MySQL host | `localhost` |
| `MYSQL_PORT` | MySQL port | `3306` |
| `MYSQL_USER` | Username | `root` |
| `MYSQL_PASSWORD` | Password | `root` |
| `MYSQL_DATABASE` | Default database | - |
| `MYSQL_ALLOW_WRITE` | Enable write operations. Supported values: `true`, `yes`, `y`; disable values: `false`, `no`, `n` (case-insensitive) | `false` |
Create a `.env` file:
```env
MCP_TRANSPORT=stdio
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
MYSQL_ALLOW_WRITE=false
```
## 🚀 Usage
### Claude Desktop Configuration
```json
{
"mcpServers": {
"MySQL MCP Tool": {
"command": "node",
"args": ["/path/to/node_modules/@itkmoon/mysql-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
```
### Cursor Configuration
```json
{
"mcpServers": {
"MySQL MCP Tool": {
"command": "node",
"args": ["/path/to/node_modules/@itkmoon/mysql-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
```
### Trae Configuration
```json
{
"mcp": {
"servers": {
"MySQL MCP Tool": {
"command": "node",
"args": ["/path/to/node_modules/@itkmoon/mysql-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
}
```
## 🧪 Connection Test
### Case 1: stdio Mode Test
Applicable to Claude Desktop, Cursor, Trae, and other AI clients, communicating with the MCP service through standard input/output.
**Step 1: Configure environment variables and start the service**
```bash
# Linux / macOS
export MYSQL_HOST=192.168.1.243
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=testdb
export MCP_TRANSPORT=stdio
# Start the service
npx @itkmoon/mysql-mcp --stdio
```
```bash
# Windows (PowerShell)
$env:MYSQL_HOST="192.168.1.243"
$env:MYSQL_PORT="3306"
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="your_password"
$env:MYSQL_DATABASE="testdb"
$env:MCP_TRANSPORT="stdio"
# Start the service
npx @itkmoon/mysql-mcp --stdio
```
**Step 2: Verify in AI client**
After successful startup, enter the following commands in the AI dialogue box for testing:
```
Please help me:
1. List all databases (using mysql_list_databases)
2. Switch to testdb database (using mysql_use_database)
3. List all tables (using mysql_list_tables)
4. Query the first 5 rows of a table (using mysql_query)
```
**Expected output example:**
```json
// 1. List databases
["information_schema", "mysql", "performance_schema", "sys", "testdb"]
// 2. Switch database
{"success": true, "database": "testdb"}
// 3. List tables
["users", "orders", "products"]
// 4. Query data
{
"columns": ["id", "name", "email", "created_at"],
"rows": [
[1, "John Doe", "john.doe@example.com", "2026-01-01"],
[2, "Jane Doe", "jane.doe@example.com", "2026-01-02"],
...
],
"rowCount": 5
}
```
---
### Case 2: HTTP/SSE Mode Test
Applicable to scenarios requiring remote access or microservice integration, communicating with the MCP service through HTTP endpoints.
**Step 1: Configure environment variables and start the HTTP service**
```bash
# Linux / macOS
export MYSQL_HOST=192.168.1.243
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=testdb
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=3000
# Start the service
npx @itkmoon/mysql-mcp --http
```
```bash
# Windows (PowerShell)
$env:MYSQL_HOST="192.168.1.243"
$env:MYSQL_PORT="3306"
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="your_password"
$env:MYSQL_DATABASE="testdb"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="3000"
# Start the service
npx @itkmoon/mysql-mcp --http
```
**Console output after successful startup:**
```
MySQL MCP Server running on HTTP port 3000
Health check: http://localhost:3000/health
Tools list: http://localhost:3000/tools
SSE endpoint: http://localhost:3000/sse
```
**Step 2: Verify endpoint availability**
```bash
# Health check
curl http://localhost:3000/health
# Expected output:
# {"status":"healthy","mysql_connected":true,"allow_write":false,"current_database":"testdb"}
# Get tool list
curl http://localhost:3000/tools
# Expected output: Returns a list of available tool names and descriptions
```
**Step 3: Test SSE connection**
```bash
# Test SSE long connection
curl -N http://localhost:3000/sse
# Expected output:
# data: {"type":"connection","status":"connected"}
#
# data: {"type":"ping"}
#
# data: {"type":"ping"}
# ... (heartbeat every 30 seconds)
```
**Step 4: Test remote access (on another device in the LAN)**
```bash
# Access from another device in the LAN (replace 192.168.1.10 with the IP of the machine running the MCP service)
curl http://192.168.1.10:3000/health
# If inaccessible, check:
# 1. Firewall allows port 3000
# 2. MySQL server (.243) allows connections from .10
```
---
## 🛠️ Available Tools
| Tool | Description |
|------|-------------|
| `mysql_query` | Execute SELECT query |
| `mysql_execute` | Execute arbitrary SQL (requires write permission) |
| `mysql_list_databases` | List all databases |
| `mysql_list_tables` | List tables in a database |
| `mysql_describe_table` | View table structure |
| `mysql_use_database` | Switch database |
| `mysql_get_current_database` | Get current database name |
| `mysql_get_permissions` | Check write permissions |
## 🔒 Access Control
Default read-only mode, only allows SELECT queries. Enable write operations:
```env
MYSQL_ALLOW_WRITE=true
```
`MYSQL_ALLOW_WRITE` supports the following values (case-insensitive):
| Value | Meaning |
|----|------|
| `true` / `yes` / `y` | Enable write operations |
| `false` / `no` / `n` | Disable write operations |
## 📄 License
MIT License
## 🔗 Links
- [GitHub](https://github.com/ITKMUnigle/MySQL-MCP-Tool)
- [npm](https://www.npmjs.com/package/@itkmoon/mysql-mcp)
