easy-mysql-mcp

A lightweight Model Context Protocol (MCP) server that lets AI assistants inspect and query a MySQL database through a safe, structured tool interface.

This project uses Node.js, TypeScript, the official MCP SDK, and mysql2/promise. It runs over stdio, so it can be used directly by MCP clients such as Claude Desktop.

Features

• MySQL connection pooling powered by mysql2/promise

• Read-only query tool for data retrieval

• Execute tool for data modification statements

• Schema discovery tools for tables, views, indexes, and triggers

• Query plan inspection with EXPLAIN

• Current user and privilege inspection

• stdout protection to prevent non-MCP logs from polluting the stdio protocol

Requirements

• Node.js 18 or newer

• npm

• A reachable MySQL-compatible database

Installation

Run the server directly with npx:

npx -y easy-mysql-mcp

For local development after cloning the repository:

cd easy-mysql-mcp
npm install
npm run build

Configuration

Configure the server with environment variables. You can provide them through your MCP client configuration or by creating a local .env file.

Example .env:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

Usage

Configure your MCP client to launch the package through npx.

For local development, build the TypeScript source first:

npm run build

Start the MCP server:

npm start

The server communicates over stdio and is normally launched by an MCP client rather than run manually.

Claude Desktop Example

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "easy-mysql-mcp": {
      "command": "npx",
      "args": ["-y", "easy-mysql-mcp"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Available Tools

Security Notes

• Use a dedicated MySQL user with the minimum permissions your assistant needs.

• Prefer read-only database credentials if you only need inspection and reporting.

• Be careful with mysql_execute, because it can modify data.

• Do not commit .env files or real database credentials to GitHub.

• Review generated SQL before running it against production data.

Development

npm run dev

This runs TypeScript in watch mode.

To create a production build:

npm run build

Project Structure

src/
  db.ts       MySQL pool and query helpers
  index.ts    MCP server and tool registration
  proxy.ts    stdout protection for stdio-based MCP transport

License

ISC