Content
# MySQL MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects Claude (or any MCP-compatible client) to a MySQL database. It exposes tools for schema inspection and running read/write queries over a stdio transport.
## Tools
| Tool | Description |
|------|-------------|
| `select_mysql_version` | Returns the connected MySQL server version |
| `list_tables` | Lists all tables in the connected database |
| `describe_table` | Shows columns, types, and constraints for a given table |
| `query` | Runs a read-only `SELECT` query with optional `?` placeholder params |
| `mutate` | Runs an `INSERT`, `UPDATE`, or `DELETE` statement with optional params |
> **Note:** `mutate` rejects `SELECT` statements — use `query` for reads.
## Requirements
- Node.js 18+
- A running MySQL instance
## Quick Install (Recommended)
### 1. Download the plugin
Go to the [Releases](https://github.com/iamdylanngo/mysql-mcp-server/releases) page and download the latest `.mcpb` file (e.g. `mysql-mcp-server-v1.0.1.mcpb`).
### 2. Install the plugin
**Via Claude Code CLI:**
```bash
claude plugin install mysql-mcp-server-v1.0.1.mcpb
```
**Via Claude Desktop:**
Double-click the `.mcpb` file — Claude Desktop will prompt you to install it.
### 3. Configure your database connection
After installation, Claude will prompt you to fill in your connection details:
| Field | Default | Description |
|-------|---------|-------------|
| Database Host | `127.0.0.1` | MySQL hostname or IP |
| Database Port | `3306` | MySQL port |
| Database User | `root` | MySQL username |
| Database Password | _(empty)_ | MySQL password |
| Database Name | _(required)_ | Database to connect to |
| Connection Pool Limit | `10` | Max concurrent connections |
You can update these settings at any time in Claude's plugin settings under **MySQL MCP Server**.
---
## Manual Setup (from source)
**1. Clone and install dependencies**
```bash
git clone https://github.com/iamdylanngo/mysql-mcp-server
cd mcp
npm install
```
**2. Configure environment**
Copy the sample env file and fill in your database credentials:
```bash
cp .env.sample .env
```
```env
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=root
DB_NAME=mydb
DB_POOL_LIMIT=10
```
**3. Build**
```bash
npm run build
```
## Usage
### Run directly
```bash
node --env-file=.env build/index.js
```
### Inspect with MCP Inspector
```bash
npm run mcp
```
### Connect to Claude Desktop
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/[absolute-path]/mysql-mcp-server/build/index.js"],
"env": {
"DB_HOST": "127.0.0.1",
"DB_PORT": "3306",
"DB_USER": "root",
"DB_PASSWORD": "your_password",
"DB_NAME": "your_database",
"DB_POOL_LIMIT": "10"
}
}
}
}
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `DB_HOST` | `localhost` | MySQL host |
| `DB_PORT` | `3306` | MySQL port |
| `DB_USER` | `root` | MySQL user |
| `DB_PASSWORD` | _(empty)_ | MySQL password |
| `DB_NAME` | `mydb` | Database name |
| `DB_POOL_LIMIT` | `10` | Connection pool size |
## Tech Stack
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) — MCP server framework
- [mysql2](https://github.com/sidorares/node-mysql2) — MySQL client with promise support
- [Zod](https://zod.dev/) — Input schema validation
- TypeScript
## License
[MIT](./LICENSE)
