# MySQL Ops MCP

**English** | [简体中文](./README.zh-CN.md)

[![npm version](https://img.shields.io/npm/v/mysql-ops-mcp.svg)](https://www.npmjs.com/package/mysql-ops-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![GitHub stars](https://img.shields.io/github/stars/GT-dinuo/mysql-ops-mcp?style=social)](https://github.com/GT-dinuo/mysql-ops-mcp)

A MySQL database MCP Server. Let AI tools like Claude Code / Cursor / Codex talk to your MySQL databases in natural language — **browse databases and tables, inspect schemas, run queries, and perform CRUD operations**, with destructive operations (DELETE / DROP) gated behind explicit user approval.

## Features

- 🗄️ **Schema browsing**: list databases, list tables, describe table structure, full table info (indexes, DDL, stats)
- 🔍 **Queries**: run `SELECT` queries against any database
- ✏️ **CRUD**: create tables, insert, update — with SQL-statement validation per tool
- 🔐 **Approval-gated destructive ops**: `delete_data` and `drop_table` always require explicit user confirmation in the client
- 🔌 **Zero install**: runs via `npx`, configured entirely through environment variables

## Installation

Requires Node.js 18+. No clone or build needed — `npx` fetches and runs the published npm package on first use (see the config below).

To build from source instead (e.g. for development):

```bash
git clone https://github.com/GT-dinuo/mysql-ops-mcp.git
cd mysql-ops-mcp
npm install
npm run build
```

Build output goes to `dist/`; the entry point is `dist/index.js`.

## Configuration

In each project where you want to use this tool, create (or append to) `.mcp.json`:

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "mysql-ops-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_DATABASE": "your_database"
      }
    }
  }
}
```

If you built from source, point the command at the local build instead: `"command": "node"`, `"args": ["/absolute/path/to/mysql-ops-mcp/dist/index.js"]`.

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `DB_HOST` | No | MySQL host, default `localhost` |
| `DB_PORT` | No | MySQL port, default `3306` |
| `DB_USER` | No | MySQL user, default `root` |
| `DB_PASSWORD` | No | MySQL password |
| `DB_DATABASE` | No | Default database; if omitted, pass `database` per tool call |

## Usage

Once configured, just ask in natural language in your AI tool:

```
List all databases
Show the structure of the users table
Query the 10 most recent orders
Get full info for the users table — indexes and DDL included
Insert a test record into the users table
Delete the test record you just inserted   ← the client will ask for your approval first
```

Destructive operations (`delete_data`, `drop_table`) are always confirmed by the MCP client before execution — nothing irreversible happens silently.

## Tool List

| Tool | Description |
|------|-------------|
| `list_databases` | List all databases |
| `list_tables` | List tables in a database |
| `describe_table` | Show table columns and types |
| `get_table_info` | Full table details: columns, indexes, DDL, stats |
| `query` | Run a SELECT query |
| `create_table` | Create a table (CREATE TABLE only) |
| `insert` | Insert rows (INSERT only) |
| `update` | Update rows (UPDATE only) |
| `delete_data` | Delete rows — requires user approval |
| `drop_table` | Drop a table — requires user approval |
| `execute_sql` | Run any custom SQL statement |

## Security

1. **Destructive operations require approval**: `delete_data` and `drop_table` are gated by the MCP client's tool-call confirmation — approve or reject each one.
2. **Statement validation**: each write tool only accepts its own SQL verb (e.g. `query` rejects anything but `SELECT`).
3. **Use a least-privilege account**: don't connect as `root` in production — create a MySQL user scoped to the databases the AI may touch.
4. **Never commit credentials**: `.env` / `.mcp.json` with real passwords must stay out of version control (`.gitignore` already covers `.env`).

## Testing the Connection

After configuring `.env` (copy from `env.example`), you can verify connectivity before wiring up the client:

```bash
cp env.example .env   # fill in real credentials
npm run test-connection
```

## Development

```bash
npm run dev    # watch mode, recompiles on change
npm run build  # build to dist/
npm start      # run the built Server
```

## License

[MIT](./LICENSE) © 2026 mysql-ops-mcp