# mysql-mcp

`mysql-mcp` is a read-only MySQL MCP server that can be used by Codex, Claude Code, and other Model Context Protocol clients.

It exposes two tools:

- `query_mysql`: execute a read-only SQL query against a configured datasource
- `list_datasources`: list the available datasource names from the config file

## Features

- Read-only query workflow through MCP stdio transport
- Multiple datasource definitions in one YAML config file
- Simple installation from PyPI once published
- Works with Codex and Claude Code global MCP configuration

## Installation

### From PyPI

```bash
pipx install mysql-mcp
```

Or with `uv`:

```bash
uv tool install mysql-mcp
```

### Local development

```bash
python3 -m pip install -e ".[dev]"
```

## Configuration

Create a YAML config file. You can start from [`config.example.yaml`](./config.example.yaml):

```yaml
datasources:
  dev:
    host: "127.0.0.1"
    port: 3306
    user: "mysql"
    password: "${MYSQL_PASSWORD}"
    database: "app_dev"
    pool_size: 5
    pool_name: "dev_pool"

query:
  default_timeout: 30
  max_rows: 10000
```

The MCP process must receive any referenced environment variables such as `MYSQL_PASSWORD`.

## Running the server

```bash
cp config.example.yaml config.yaml
mysql-mcp /absolute/path/to/config.yaml
```

## Codex setup

Add it as a global MCP server:

```bash
codex mcp add mysql-mcp \
  --env MYSQL_PASSWORD=your-password \
  -- mysql-mcp /absolute/path/to/config.yaml
```

If you prefer not to preinstall the package, you can also run it through `uvx`:

```bash
codex mcp add mysql-mcp \
  --env MYSQL_PASSWORD=your-password \
  -- uvx mysql-mcp /absolute/path/to/config.yaml
```

## Claude Code setup

Add this to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "type": "stdio",
      "command": "mysql-mcp",
      "args": ["/absolute/path/to/config.yaml"],
      "env": {
        "MYSQL_PASSWORD": "your-password"
      }
    }
  }
}
```

Or use `uvx`:

```json
{
  "mcpServers": {
    "mysql-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mysql-mcp", "/absolute/path/to/config.yaml"],
      "env": {
        "MYSQL_PASSWORD": "your-password"
      }
    }
  }
}
```

## Publish to PyPI

1. Update the version in `pyproject.toml`.
2. Build the package:

```bash
python3 -m build
```

3. Upload to TestPyPI first:

```bash
python3 -m twine upload --repository testpypi dist/*
```

4. Upload to PyPI:

```bash
python3 -m twine upload dist/*
```

## Development

Run tests:

```bash
pytest -q
```

Build artifacts:

```bash
python3 -m build
```