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.
| Variable | Required | Default | Description |
|---|---|---|---|
MYSQL_HOST | Yes | - | MySQL host name or IP address |
MYSQL_PORT | No | 3306 | MySQL port |
MYSQL_USER | Yes | - | MySQL user name |
MYSQL_PASSWORD | Yes | - | MySQL password |
MYSQL_DATABASE | Yes | - | Default database/schema |
MYSQL_CONNECTION_LIMIT | No | 10 | Maximum number of active pool connections |
MYSQL_MAX_IDLE | No | 10 | Maximum number of idle pool connections |
MYSQL_IDLE_TIMEOUT | No | 60000 | Idle connection timeout in milliseconds |
MYSQL_QUEUE_LIMIT | No | 0 | Maximum queued connection requests, where 0 means unlimited |
MYSQL_WAIT_FOR_CONNECTIONS | No | true | Whether the pool waits when all connections are busy |
MYSQL_ENABLE_KEEP_ALIVE | No | true | Whether TCP keep-alive is enabled |
MYSQL_KEEP_ALIVE_INITIAL_DELAY | No | 0 | Initial TCP keep-alive delay in milliseconds |
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
| Tool | Description |
|---|---|
mysql_query | Execute a SQL query intended for data retrieval, such as SELECT |
mysql_execute | Execute a data modification statement, such as INSERT, UPDATE, or DELETE |
explain_query | Run EXPLAIN for a SQL query and return the execution plan |
list_tables | List base tables in the current database, including approximate row counts and comments |
list_views | List views in the current database |
describe_table | Show column information for one or more tables |
describe_index | Show indexes for a table |
list_triggers | List triggers in the current database |
get_current_privileges | Show the current MySQL user and grants |
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
.envfiles 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