mysql-mcp

A Model Context Protocol (MCP) server that gives AI agents direct access to MySQL databases.

What It Can Do

Data Query & Mutation

• `execute_query` — Run SELECT, INSERT, UPDATE, or DELETE statements with parameterized query support (`?` placeholders)
• `execute_transaction` — Execute multiple statements as an atomic batch; if any statement fails the entire transaction is automatically rolled back

Schema Management

• `create_table` — Create a new table
• `alter_table` — Add/drop columns, rename columns, add indexes, and more
• `drop_table` — Drop a table (requires `ALLOW_DESTRUCTIVE_DDL=true`)
• `show_tables` — List all tables in a database
• `describe_table` — Show column structure of a table

Database Management

• `list_databases` — List all user databases (system databases excluded)
• `create_database` — Create a new database with optional charset and collation
• `drop_database` — Drop a database (requires `ALLOW_DESTRUCTIVE_DDL=true`)

Introspection

• `ping` — Check MySQL connection health
• `show_columns` — Show detailed column information for a table
• `get_server_info` — Return MySQL version, character set, and collation (read-only)

Multi-Database Support

Every tool accepts a `database` parameter. You can query different databases within the same session without any extra configuration.

What It Cannot Do

The following operations are permanently blocked by the security filter and cannot be bypassed under any circumstances:

Additional constraints:

• Multiple statements separated by `;` in a single call are not allowed — use `execute_transaction` instead
• `drop_table` and `drop_database` are disabled by default and will return an error unless `ALLOW_DESTRUCTIVE_DDL=true` is set
• Query results are capped at `MAX_ROWS` rows (default: 1000); add a `LIMIT` clause for large tables

Installation

Requirements: Node.js 20+

git clone https://github.com/turkeryildirim/mysql-mcp
cd mysql-mcp
npm install
npm run build

Copy the example environment file and fill in your credentials:

cp .env.example .env

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=mcp_user
MYSQL_PASSWORD=your_password

# Optional
MYSQL_DATABASE=default_db
MYSQL_POOL_SIZE=10
MAX_ROWS=1000
ALLOW_DESTRUCTIVE_DDL=false

Creating a Dedicated MySQL User (Recommended)

Create a least-privilege MySQL user for the MCP server:

CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX
  ON *.* TO 'mcp_user'@'localhost';
FLUSH PRIVILEGES;

> Do not grant `SUPER`, `FILE`, `RELOAD`, or `GRANT OPTION`.

Claude Desktop Integration

Open the Claude Desktop config file:

• Windows: `%APPDATA%\Claude\claude_desktop_config.json`
• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following block under `mcpServers`:

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "",
        "MAX_ROWS": "1000",
        "ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

Restart Claude Desktop. You should see the `mysql` server listed in the tools panel.

Claude CLI Integration

Option 1: `.mcp.json` — Project-scoped (Recommended)

Create a `.mcp.json` file in your project root:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "your_password",
        "ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

The server loads automatically whenever you run `claude` from that directory.

Option 2: Global configuration

claude mcp add mysql -- node /absolute/path/to/mysql-mcp/dist/index.js

To include environment variables:

claude mcp add mysql \
  -e MYSQL_HOST=localhost \
  -e MYSQL_USER=mcp_user \
  -e MYSQL_PASSWORD=your_password \
  -- node /absolute/path/to/mysql-mcp/dist/index.js

Verify the setup:

claude mcp list
claude mcp get mysql

Example Prompts

Once connected, you can instruct the agent in natural language:

Show me the structure of the users table in testdb
Fetch the last 10 orders from testdb.orders
Create a products table in testdb with id, name, price, and stock columns
Run the following two INSERTs as a single transaction: ...

Development

npm run dev        # Watch mode (rebuilds on change)
npm test           # Unit tests (no MySQL connection required)
npm run build      # Production build → dist/