# MySQL MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server that connects Claude Code to MySQL databases. Once configured, you can query your database using natural language directly in Claude Code.

## Features

- **query**: Execute SELECT queries on your MySQL database
- **list_tables**: List all tables in the database
- **describe_table**: Get the schema/structure of a specific table

## Quick Start

Choose one of the installation methods below, then add the configuration to Claude Code.

### Option 1: Using npx

No installation needed. Add this to your Claude Code config:

```json
{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}
```

### Option 2: Install globally from npm

```bash
npm install -g mysql-mcp-server
```

Then add this to your Claude Code config:

```json
{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "mysql-mcp-server",
      "args": [],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}
```

### Option 3: Clone from GitHub

```bash
git clone https://github.com/Nordstrom-Sandbox/mysql-mcp-server.git
cd mysql-mcp-server
npm install
```

Then add this to your Claude Code config (use the actual path where you cloned it):

```json
{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "node",
      "args": ["/full/path/to/mysql-mcp-server/index.js"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}
```

## Configuration

### Claude Code Config Location

- **macOS/Linux**: `~/.claude.json`
- **Windows**: `%USERPROFILE%\.claude.json`

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MYSQL_HOST` | MySQL server hostname | localhost |
| `MYSQL_PORT` | MySQL server port | 3306 |
| `MYSQL_USER` | MySQL username | root |
| `MYSQL_PASSWORD` | MySQL password | (empty) |
| `MYSQL_DATABASE` | Database name | (required) |

### Restart Claude Code

After adding the configuration, **restart Claude Code** for the changes to take effect. Claude Code automatically starts and manages the MCP server - you don't need to run it manually.

## Usage Examples

Once configured, just talk to Claude naturally:

- "Show me all the tables in the database"
- "What's the schema of the users table?"
- "Show me the first 10 users"
- "Update the status to 'active' for user_id 123"

## Security Notes

1. **Never commit credentials** to version control
2. **Use read-only database users** when possible
3. The `query` tool only allows SELECT statements
4. The `execute` tool can run INSERT/UPDATE/DELETE - use with caution

## Troubleshooting

### Connection Issues

1. Verify MySQL is running
2. Check credentials are correct
3. Ensure the database exists
4. Check firewall settings for remote servers
5. Look at Claude Code logs for error messages

### Permission Issues

- Ensure the MySQL user has appropriate grants for the database
- Check that the database name is correct

## For Contributors

### Development Setup

```bash
git clone https://github.com/Nordstrom-Sandbox/mysql-mcp-server.git
cd mysql-mcp-server
npm install
```

### Testing Locally

```bash
MYSQL_HOST=localhost \
MYSQL_USER=root \
MYSQL_PASSWORD=your_password \
MYSQL_DATABASE=your_database \
node index.js
```

The server communicates via stdio using the MCP protocol.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.